Core Concepts

Spine IDs

Every agent registered with Spineforge gets a permanent, stable identifier — its Spine ID.

What is a Spine ID?

A Spine ID is a UUID-4 assigned to an agent at registration time. It is stable: the same agent_name always resolves to the same Spine ID across process restarts, machine reboots, and redeployments.

The Spine ID is the anchor for every other Spineforge concept — telemetry events, credential leases, and access tokens all carry it as a claim.

Identity resolution

When you call spineforge.init(agent_name="my-agent"):

  1. Offline mode (no registry URL) — the SDK looks up agent_name in .spineforge/registry.json. If it exists, returns the same UUID. If not, generates a new UUID-4 and persists it.
  2. Connected mode (registry URL set) — the SDK generates or loads an Ed25519 keypair from .spineforge/agent_key.pem, then registers the public key with the backend. The backend assigns a server-scoped Spine ID and returns it. That server-assigned ID is used for all subsequent operations.

Ed25519 keypairs

In connected mode, each agent has an asymmetric keypair. The key algorithm is Ed25519 — a modern elliptic curve signature algorithm with small key sizes and fast verification.

  • Private key — generated on first init, stored at .spineforge/agent_key.pem. Never transmitted anywhere.
  • Public key — sent to the registry during registration. Used by the registry to verify JWT assertions from this agent.
Key rotation: If you delete agent_key.pem, the agent will generate a new keypair on next init and re-register. The old Spine ID will be orphaned. Back up your key file if you need identity continuity.

The registry.json file

In offline mode, identity is persisted in .spineforge/registry.json:

{
  "agents": {
    "my-research-agent": {
      "spine_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2025-01-15T10:23:45.123Z"
    }
  }
}

The data directory defaults to the current working directory. Override it with SPINEFORGE_DATA_DIR or the data_dir kwarg to init().

Ownership and assignment

In connected mode with SSO/OIDC configured, each agent can have an owner_employee_id — the identity of the human responsible for it. This is populated server-side from a verified identity token (Google Workspace, Okta, or Azure AD). Admin-assigned ownership logs both who assigned and the verified owner.

See SSO / OIDC configuration for setup details.

Spine ID in JWT claims

The Spine ID appears as the sub (subject) claim in every access token issued to or for an agent:

{
  "sub": "spine_a1b2c3d4",    // This agent's Spine ID
  "aud": "registry",           // Or target agent's Spine ID
  "scope": "credential:lease",
  "iat": 1735689600,
  "exp": 1735693200
}

Next steps

  • Credential Leasing — how agents use their Spine ID to get credentials
  • Scopes — JWT scope claims and set membership enforcement
  • Security Model — the full architecture from an auditor's perspective