Reference

Security Model

The complete authentication and credential architecture — at docs depth. For the questionnaire-ready summary, see the Security page.

Identity: Ed25519 + RFC 7523

On first spineforge.init() with a registry URL:

  1. SDK generates an Ed25519 keypair using a CSPRNG
  2. Private key written to .spineforge/agent_key.pem — never transmitted
  3. Public key sent to POST /agents/register over HTTPS
  4. Registry assigns a server-scoped Spine ID and returns it

When the agent needs an access token (e.g. before a credential lease):

  1. SDK constructs a JWT: { sub: spine_id, aud: "registry", scope, iat, exp }
  2. JWT signed with Ed25519 private key
  3. JWT submitted to POST /auth/token
  4. Registry verifies signature using stored public key
  5. Registry checks scope subset membership against allowed_scopes
  6. Short-lived access token returned

Credential brokering: /credentials/lease

Flow after a valid access token is obtained:

  1. POST /credentials/lease { secret_name: "openai-api-key" } with Bearer token
  2. Registry validates Bearer token — checks expiry, scope (credential:lease), and agent status (not revoked)
  3. Registry retrieves raw secret from encrypted vault
  4. Returns { value: "sk-...", expires_at: "..." }
  5. SDK returns raw value to calling code — value is not persisted by the SDK

Revocation — precise semantics

When an agent is revoked:

  • Immediate: Status field on the agent record is set to revoked
  • Immediate: Future token requests rejected (step 4 above fails)
  • Immediate: Future lease requests rejected
  • NOT immediate: Lease copies already in the agent's memory are not invalidated — providers don't support short-lived scoped keys
  • Lag: Full access loss = remaining TTL on the current lease
To force immediate loss of access: rotate the underlying provider API key in your Spineforge vault and in the provider's dashboard. This invalidates all existing copies regardless of TTL.

Shadow agent detection

The primary defense is credential custody. If raw keys exist only in Spineforge, unregistered agents have no credential path. This requires the onboarding migration — removing keys from env files, shared vaults, and CI.

Secondary signal today: billing deltas across provider billing portals vs. Spineforge-attributed usage. Significant divergence may indicate out-of-band usage.

Phase 2 (not shipped): per-key reconciliation against provider Admin APIs. Confirmed for OpenAI and Anthropic. Groq has no confirmed Admin API equivalent — unresolved.

JWKS endpoint for agent-to-agent verification

The registry exposes a JWKS endpoint at GET /well-known/jwks.json. Receiving agents fetch and cache this. When a token arrives with aud: spine_worker_xyz, the receiving agent verifies the signature locally against the cached JWKS — no registry roundtrip needed.

Data path commitment

Spineforge is never in the data path. Agents call providers directly. The OTel span pipeline captures events after the fact, asynchronously. If Spineforge is unreachable, agents keep running. The FileSink absorbs events locally. APISink retries on recovery.

Next steps