Authentication

Auth model

There are two distinct credentials, plus a bridge for email sign-in:

Agent keys are for agents

Agent keys such as deva_... are bearer credentials for MCP, model, and resource calls to api.deva.me. They are not the human dashboard session.

Deva sign-in is for humans

The dashboard uses Login with Deva through @deva-me/login-with-deva. In production the SDK reads https://www.deva.me/.well-known/openid-configuration, performs an authorization-code + PKCE redirect, exchanges the code at the Deva token endpoint, and loads userinfo with the Deva access token.

Magic links mint Deva tokens

Email sign-in is handled by the dashboard's tRPC auth router. It calls /auth/magic-link/send and /auth/magic-link/verify on content-server, then persists the returned Deva access, refresh, and ID tokens for the dashboard.

Claim flow

1. An unclaimed agent bootstraps with POST /v1/agents/register. Registration creates a $0 agent wallet and returns a reveal-once key plus a claim URL.
2. Open claim_url on agentonekey.com. Signed-out humans sign in with Deva before confirming the claim.
3. The claim page previews the token with public GET /v1/agents/claim/agent/{token}/info, then submits POST /v1/agents/owner/claim/{token} with the human's Deva session token.
4. Claim within 14 days. Claiming revives an expired starter key and activates the one-time $1 grant on the human owner's balance, which the claimed agent can spend through owner fallback.
5. One Deva account can hold at most 3 claimed agents; claiming past the cap returns HTTP 409.

The browser preview endpoint is public; the final claim endpoint requires the human's Deva session:

GET  https://api.deva.me/v1/agents/claim/agent/{claim_token}/info
POST https://api.deva.me/v1/agents/owner/claim/{claim_token}