Credential Leasing

The mechanism that keeps raw provider keys out of agent hands — and makes shadow agents structurally impossible.

The problem credential leasing solves

When agents read API keys from environment variables, any agent — registered or not — can use those keys. There's no distinction between a registered research agent and a rogue script in the same environment. Credential leasing replaces that pattern.

How leasing works

Instead of reading from env:

# Without Spineforge — raw key from env
import os
api_key = os.getenv("OPENAI_API_KEY")   # any process can do this

With credential leasing:

import spineforge

spine = spineforge.init(
    agent_name="research-agent",
    allowed_scopes=["credential:lease"],
)

# The agent proves its identity and receives a short-lived copy
api_key = spine.lease_credential("openai-api-key")

What happens under the hood

1. Token acquisition. The SDK calls spine.request_token(scopes=["credential:lease"], aud="registry") internally. This constructs a JWT signed with the agent's private key and submits it to the registry.
2. Scope validation. The registry verifies the JWT signature and checks that credential:lease is in the agent's declared allowed scopes. If it isn't, the request fails.
3. Lease issuance. POST /credentials/lease returns a short-TTL working copy of the requested secret. The raw key is never stored on the agent — it arrives as a response body, is used, and expires.

The structural guarantee

Credential custody holds only if raw provider keys are removed from every other location — env files, .env, shared vaults, CI secrets — and stored exclusively in Spineforge.

Revocation — precise semantics

When you revoke or suspend an agent in the Spineforge dashboard:

• Immediate effect: Future lease requests are rejected. The agent cannot obtain any new credentials.
• Bounded lag: A lease copy already in the agent's possession remains valid until its TTL expires. Most LLM providers do not support natively short-lived scoped keys, so there is no mechanism to invalidate an already-issued copy.

Lease TTL

Lease TTLs are configured at the org level. The default is short-lived (minutes to hours, not days). When a lease expires, the agent must call spine.lease_credential() again — the SDK handles token refresh automatically.

Full code example

import spineforge

spine = spineforge.init(
    agent_name="research-agent",
    allowed_scopes=["telemetry:write", "credential:lease"],
)

with spine.run(input="Analyse Q3 earnings") as run:
    # Lease — short-lived working copy, auto-refreshed
    openai_key = spine.lease_credential("openai-api-key")
    groq_key   = spine.lease_credential("groq-api-key")

    from openai import OpenAI
    client = OpenAI(api_key=openai_key)

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Analyse Q3 earnings"}]
    )
    run.set_output(response.choices[0].message.content)

Next steps

• Scopes — how credential:lease and other scopes are enforced
• Security Model — the full credential brokering architecture
• SDK Reference — lease_credential() and request_token() API