1. Agent Identity
How identity is established
Keypair generation
On first init(), the SDK generates an Ed25519 keypair. The private key is written to .spineforge/agent_key.pem on the agent's local filesystem. It is never transmitted to Spineforge or any other party.
Public key registration
The public key is sent to the Spineforge registry over HTTPS. The registry assigns a permanent Spine ID (UUID) to the (agent_name, public_key) tuple and returns it to the agent.
JWT assertion flow (RFC 7523)
When the agent needs an access token, it constructs a JWT containing {sub: spine_id, aud: 'registry', iat, exp} and signs it with the private key. The registry verifies the signature against the stored public key. No password is involved in this exchange.
JWT Token Structure
// JWT claims issued after RFC 7523 assertion
{
"sub": "spine_abc123", // Spine ID
"aud": "registry", // or target agent spine_id
"scope": "telemetry:write credential:lease",
"iat": 1735689600,
"exp": 1735693200 // ~1 hour TTL
}2. Credential Brokering
Agents never hold raw provider keys. They lease short-lived copies from the Spineforge registry using their identity token. This is the structural mechanism that prevents unregistered agents from accessing org credentials.
Lease flow
The agent calls spine.lease_credential('openai-api-key'). Under the hood, it presents its JWT to POST /credentials/lease. The registry validates identity, checks scopes, and returns a short-TTL working copy of the key.
What 'short-lived' means
Leased credentials expire on a configured TTL. The agent must re-lease when it expires. Spineforge controls the re-lease gate — a revoked or suspended agent cannot obtain a new lease.
Onboarding migration requirement
For credential custody to hold, raw provider keys must be removed from every other location — env files, .env, shared vaults, CI secrets — and stored only in Spineforge. This is a real onboarding step, not optional fine print.
Revocation semantics — read this precisely
Most LLM providers — including Groq — do not support natively short-lived scoped keys. Revoking an agent in Spineforge blocks all future re-leasing immediately. It does not invalidate a lease copy already in the agent's possession. There is bounded lag between revocation and full loss of access — the length of the remaining TTL on the current lease. We do not claim instant kill-switch revocation because that would not be accurate.
3. Scope Enforcement
Every agent declares its allowed scopes at registration time. Tokens carry those scopes as claims. Validation is pure set membership — if the requested scope isn't in the declared set, the token is denied.
import spineforge
spine = spineforge.init(
agent_name="research-agent",
allowed_scopes=[
"telemetry:write",
"credential:lease",
"tools:web_search",
]
)
# Later — can only request declared scopes
token = spine.request_token(
scopes=["tools:web_search"],
aud="tool-calling-agent"
)No partial grants
If an agent requests a scope not in its declared set, the request fails. There is no server-side narrowing — denial is complete.
Agent-to-agent delegation
Set aud to the target agent's Spine ID instead of 'registry'. The receiving agent verifies the JWT locally against a cached JWKS — no roundtrip to Spineforge.
Scope backfill in progress
Scope-based authorization for existing agents is currently being completed. This is an in-progress feature, not fully shipped for all agent types yet.
4. Shadow Agent Detection
Spineforge's primary defense against shadow agents — agents not registered in the system — is credential custody: if raw keys are removed from every env and vault, unregistered agents have no path to a working credential.
Shipped — Credential custody
The primary defense. Raw provider keys live only in Spineforge. Any agent that isn't registered can't lease credentials. Billing deltas across providers serve as a coarse secondary signal today.
Phase 2 — Per-key provider reconciliation
Cross-referencing Spineforge usage against provider Admin APIs (OpenAI and Anthropic confirmed) to detect unaccounted-for usage. Groq has no confirmed Admin API equivalent — this is unresolved. Phase 2, not shipped.
5. Core Architectural Commitments
Never in the data path
Agents call LLM and tool providers directly. Spineforge observes asynchronously via the OTel span pipeline. Your agents' reliability does not depend on Spineforge being up.
Private keys never transmitted
Ed25519 private keys are generated and stored locally. Only the public key reaches Spineforge. There is no mechanism in the SDK to exfiltrate the private key.
Signed JWTs over passwords
All authentication uses asymmetric signed assertions. There are no shared secrets between agents and the registry — each agent proves identity by signing with its private key.
JWKS endpoint for agent verification
Agents that receive delegated tokens verify them locally against the registry's JWKS endpoint (cached). No agent-to-agent calls need a Spineforge roundtrip on the receive side.
6. Competitive Landscape
Spineforge is not first to the agent identity space. Okta for AI Agents, Microsoft Entra Agent ID, CyberArk, Runlayer, Keycard, Veza, and Teleport all ship overlapping identity products. Spineforge's wedge is the bundled identity + observability combination — not being first to agent identity.
Questions for your questionnaire?
The docs security model page covers the same ground at full technical depth. Or reach out directly.