Authentication API
Proof-first auth endpoints and compatibility token flows
Overview
New agent integrations should send X-Lemma-Credential directly to protected endpoints. Use the endpoints on this page for hosted wallet callbacks, proof exchange, and compatibility token management.
Default: proof-first via X-Lemma-Credential.
Compatibility only: exchange proof for short-lived bearer tokens when an older runtime cannot yet send the lemma header directly.
Base URL
https://lemma.id
Start Hosted SDK Auth
/auth/sdk-request
Creates a one-time state for hosted auth redirects. Typically called by integrations that use the hosted callback flow.
Hosted SDK Callback
/auth/sdk-callback
Consumes state, verifies callback payload, and returns control to the integration origin.
Optional: Exchange Verified Proof for Access Token
/api/auth/exchange-proof
Compatibility path for legacy bearer-token integrations. Proof-first integrations should send X-Lemma-Credential directly instead of exchanging for lm_at_....
Request
{
"credential": { "...": "signed lemma object" },
"site_id": "example.com",
"requested_scope": ["read"],
"ttl_seconds": 900
}
Response
{
"access_token": "lm_at_...",
"token_type": "Bearer",
"expires_in": 900,
"site_id": "example.com",
"scope": ["read"],
"permission_id": "admin_access"
}
Primary Protected-Route Contract
Protected routes should accept the lemma header directly:
POST /api/protected/action
X-Lemma-Credential: <base64url(full signed lemma)>
Verify trust, signature, expiry, site binding, and required scope server-side. Treat bearer transport as a migration aid, not the source of truth.
Token Management (API Key Protected)
/api/auth/introspect
/api/auth/revoke
These endpoints require X-API-Key and are intended for trusted backend/service calls.
Use Which Path?
| Scenario | Recommended path |
|---|---|
| New agent or runtime integration | Send X-Lemma-Credential directly |
| Legacy bearer-only transport | POST /api/auth/exchange-proof to obtain lm_at_... |
| Token diagnostics and revocation | /api/auth/introspect and /api/auth/revoke with API key |