Authentication

An agent authenticates to a Server one of two ways:

When to choose which. Reach for an API key when you are getting started, scripting, or running where no IdP is available. Choose OIDC certs when an identity provider already issues your workloads' identities (Okta, Auth0, Entra ID, Keycloak, a cloud workload-identity system) — then no long-lived secret sits in your agent's environment, and a leaked credential expires on its own in minutes rather than living until someone revokes it.

This page covers the API-key path end to end, then the OIDC-cert path — the AGLedger cert exchange and a per-IdP recipe table. For endpoint and field-level detail, see the API reference.

API-key path

1. Mint a key

An operator mints a key with POST /v1/admin/api-keys (admin or platform key). Give it a role (agent, admin, or platform) and a scope profile — do not enumerate scopes by hand:

curl -s -X POST -H "Authorization: Bearer $AGLEDGER_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"role":"agent","ownerType":"agent","ownerId":"<agent-id>","scopeProfile":"agent-full","label":"invoice-bot prod key"}' \
  "$AGLEDGER_URL/v1/admin/api-keys"

{
  "keyId": "019e61f1-c755-710f-93fb-820b2f4a8446",
  "apiKey": "agl_agt_E85ITAKOvk5KBDXepDWfxurjnnZtbPWky19wdoc5fxE",
  "role": "agent",
  "ownerId": "019e61d4-fbb9-780f-b110-8a64ab46920f",
  "scopeProfile": "agent-full",
  "scopes": ["records:read","records:write","completions:read","completions:write", "..."],
  "expiresAt": null,
  "nextSteps": [
    { "action": "Test the key", "method": "GET", "href": "/v1/auth/me", "description": "Verify the new API key works by calling GET /v1/auth/me with it as a Bearer token" }
  ]
}

The raw apiKey is returned in this response and only this response — it cannot be retrieved later. Capture it now. The ownerId is an agent you created via POST /v1/admin/agents; list agents with GET /v1/admin/agents.

Scope profiles (agent-full, admin-standard, admin-observer, …) are listed, with the scopes and roles each carries, at the unauthenticated discovery surface — read it rather than guessing scope names:

curl -s "$AGLEDGER_URL/v1/scope-profiles"

2. Make an authenticated call

Send the key as Authorization: Bearer. Verify it resolves before wiring it into an agent:

curl -s -H "Authorization: Bearer $AGLEDGER_KEY" "$AGLEDGER_URL/v1/auth/me"

{
  "apiKeyId": "019e61f1-c755-710f-93fb-820b2f4a8446",
  "role": "agent",
  "ownerId": "019e61d4-fbb9-780f-b110-8a64ab46920f",
  "ownerType": "agent",
  "orgId": "019e61d3-c074-73cf-b14b-50b5e94c6845",
  "scopes": ["records:read","records:write", "..."],
  "name": "docs-demo-agent",
  "authType": "api_key",
  "cert": null,
  "oidc": null
}

GET /v1/auth/me is the canonical "who am I" call — it echoes the resolved identity, scopes, and authType. From here the agent uses the same Bearer header on every request.

3. Failure modes

A missing or invalid key returns 401 with a detail that says which:

{"status":401,"error":"UNAUTHORIZED","detail":"Missing API key. Use Authorization: Bearer <key>"}
{"status":401,"error":"UNAUTHORIZED","detail":"Invalid or inactive API key"}

A valid key that lacks the scope for an action returns 403 naming the missing scope or required role — mint a key with the right scope profile rather than widening an existing one.

Rotation and revocation

API keys are long-lived (expiresAt: null by default). Treat the agl_… value as a secret: store it in your secret manager, never in source. Revoke a compromised key by toggling it inactive with PATCH /v1/admin/api-keys/{keyId} (body { "isActive": false }), or revoke many at once with POST /v1/admin/api-keys/bulk-revoke. Revocation is immediate.

OIDC-cert path (recommended for production)

Instead of carrying a long-lived secret, an agent presents a token from your own identity provider and exchanges it for a certificate valid for minutes. Three steps: register the issuer once, then per agent — exchange a token for a cert, and use the cert.

1. Register the issuer (once, per IdP)

An operator registers your IdP as a trust anchor with POST /v1/admin/trusted-issuers (platform key). claimMapping tells the Server which token claims carry the agent identity and scopes:

curl -s -X POST -H "Authorization: Bearer $AGLEDGER_PLATFORM_KEY" -H "Content-Type: application/json" \
  -d '{
    "orgId": "<org-id>",
    "issuerUrl": "https://your-tenant.idp.example/",
    "expectedAudience": "agledger",
    "appliesTo": "agent",
    "claimMapping": { "scopes": "agledger_scopes", "agent_id": "agledger_agent_id" },
    "maxCredentialTtlSeconds": 600
  }' \
  "$AGLEDGER_URL/v1/admin/trusted-issuers"

{
  "id": "019e61fe-dddd-7123-a36d-f292a5952984",
  "issuerUrl": "https://your-tenant.idp.example/",
  "jwksUri": "https://your-tenant.idp.example/.well-known/jwks.json",
  "expectedAudience": "agledger",
  "appliesTo": "agent",
  "claimMapping": { "scopes": "agledger_scopes", "agent_id": "agledger_agent_id" },
  "maxCredentialTtlSeconds": 600
}

Omit jwksUri to let the Server discover it from ${issuerUrl}/.well-known/openid-configuration; supply it explicitly if your IdP does not publish discovery. issuerUrl must exactly match the iss claim in the tokens the IdP issues, and expectedAudience must match their aud.

2. Exchange a token for a cert

The agent obtains an OIDC token from your IdP (see the per-IdP recipes below), generates an Ed25519 keypair, and proves possession of the private key — the proof is Ed25519("agledger.oidc.cert.v1\n" + sub), base64. It then calls POST /v1/auth/oidc/cert:

curl -s -X POST -H "Content-Type: application/json" \
  -d '{ "oidcToken": "<jwt-from-idp>", "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "<base64url>" }, "proofOfPossession": "<base64-sig>" }' \
  "$AGLEDGER_URL/v1/auth/oidc/cert"

{
  "cert": {
    "id": "b6049896-63d8-4e8e-82c9-6cd8689689a5",
    "orgId": "019e61d3-c074-73cf-b14b-50b5e94c6845",
    "agentId": "019e61d4-fbb9-780f-b110-8a64ab46920f",
    "oidcIss": "https://your-tenant.idp.example/",
    "oidcSub": "workload|docs-demo",
    "publicKeyThumbprint": "sha256:369cb75b1875df7091e609321d411d886e91c0c4ec9c363edba5fb44ff2e9796",
    "scopes": ["records:write", "records:read"],
    "issuedAt": "2026-05-26T01:55:53.000Z",
    "expiresAt": "2026-05-26T02:05:53.000Z"
  },
  "certJws": "eyJhbGciOiJFZERTQSIsImtpZCI6IjZhNjM5MjQ4…"
}

The cert is bound to the agent's key (publicKeyThumbprint), carries only the scopes the IdP asserted, and expires in minutes (maxCredentialTtlSeconds, capped at 3600). The agent re-exchanges before expiry; a leaked cert is dead almost immediately.

3. Use the cert

Send certJws as the Bearer token. GET /v1/auth/me now reports cert-backed identity — note authType and the populated cert / oidc blocks (which were null on the API-key path):

{
  "role": "agent",
  "ownerId": "019e61d4-fbb9-780f-b110-8a64ab46920f",
  "scopes": ["records:write", "records:read"],
  "authType": "ephemeral_cert",
  "cert": { "id": "b6049896-…", "thumbprint": "sha256:369cb75b…", "expiresAt": "2026-05-26T02:05:53.000Z" },
  "oidc": { "iss": "https://your-tenant.idp.example/", "sub": "workload|docs-demo" }
}

A cert-authenticated POST /v1/records notarizes exactly as an API key would — the chain entry carries the OIDC identity that authorized it.

Optional per-request attestation

On top of cert auth, an agent can sign each request body with its bound key and send X-Agent-Signature + X-Agent-Signature-Content-Hash (Ed25519(sha256(rawBody))). The chain entry then carries the agent's own client-side attestation of that specific request, not just the cert.

Per-IdP recipes

Every IdP uses the same two AGLedger calls above. What differs per IdP is the issuer URL, the audience to request, and how the workload obtains a token. Configure your IdP to issue the agent identity and scopes under the claim names you set in claimMapping (above: agledger_agent_id, agledger_scopes).

| IdP | issuerUrl shape | How the workload gets a token | |---|---|---| | Okta | https://<tenant>.okta.com/oauth2/<authServerId> | Client-credentials grant against the authorization server's /v1/token, with aud set to your expectedAudience | | Auth0 | https://<tenant>.auth0.com/ | Client-credentials grant with the audience parameter set to your expectedAudience | | Entra ID | https://login.microsoftonline.com/<tenantId>/v2.0 | Client-credentials (or managed identity) token for the app registration whose URI is your expectedAudience | | Keycloak | https://<host>/realms/<realm> | Service-account client-credentials grant against the realm token endpoint | | GCP Workload Identity | https://accounts.google.com (or your WIF pool issuer) | Fetch an instance/workload identity token from the metadata server with audience set to your expectedAudience | | Kubernetes service account | the cluster's projected-token issuer (kubectl get --raw /.well-known/openid-configuration) | Mount a projected service-account token with audience: <expectedAudience>; the pod reads it from the token file |

For each: set issuerUrl/expectedAudience on the trusted issuer to match what the IdP issues, register it (step 1), then have the workload obtain a token its standard way and exchange it (steps 2–3). The exchange and cert usage are identical across IdPs.

API-key path and the AGLedger cert-exchange flow (register issuer → exchange → cert-bearer call) validated against API v0.25.4 on 2026-05-25 using a local OIDC issuer. The per-IdP issuerUrl / expectedAudience / token-acquisition details follow each provider's standard setup and should be confirmed against your live IdP.