--- title: How agents authenticate with past.dev description: How to obtain and use credentials for the past.dev Memory API and MCP server. canonical: https://past.dev/auth.md last-updated: 2026-09-30 --- # How agents authenticate with past.dev past.dev has three authentication methods. The REST Memory API at https://api.past.dev/api/v1 takes bearer API keys, and agent access tokens that an agent gets for one person through the agent_auth flow. The product MCP server at https://app.past.dev/mcp uses OAuth through WorkOS AuthKit. The documentation MCP server at https://past.dev/mcp is public and requires no credentials. ## Discover - REST: a call to https://api.past.dev/api/v1 with no credential answers 401 with a WWW-Authenticate challenge carrying resource_metadata. The RFC 9728 document at https://app.past.dev/.well-known/oauth-protected-resource/api/v1 names the authorization server https://sso.past.dev and the scopes memory:read and memory:write. The RFC 8414 metadata at https://sso.past.dev/.well-known/oauth-authorization-server carries the agent_auth block: identity_endpoint, claim_endpoint, revocation_endpoint and identity_types_supported, which lists service_auth only. The OpenAPI description at https://past.dev/openapi.json declares the bearer schemes and the scope of each operation. - MCP: the server answers 401 with a WWW-Authenticate challenge carrying resource_metadata, and RFC 9728 protected-resource metadata lives at https://api.past.dev/.well-known/oauth-protected-resource, naming the authorization server. RFC 8414 authorization-server metadata is served at the AS origin. ## Pick a method - Calling the REST API from software: a bearer project key (keys start with past_sk_). - Calling the REST API as an agent for one person, with no pasted key: an agent access token. See Register. - Managing projects and minting project keys from software: the organization's management key (keys start with past_mk_), created once per organization in the console. It reads no memory. - Connecting an MCP client for a person: OAuth authorization code with PKCE. The client handles the flow automatically. Dynamic Client Registration is supported, so clients do not require advance provisioning. - Reading these docs over MCP: no authentication required. ## Register An agent registers with the agent_auth flow. Follow https://api.past.dev/auth.md: it gives each command in order. The flow is service_auth: the agent sends the email address of the person to the identity_endpoint, and every registration is bound to a person. Anonymous registration is not available. The person must have a past.dev account. A person without one signs up in a browser at https://sso.past.dev/sign-up. For API keys there is no registration flow. After sign-up, create the management key in the console. Mint project keys in the console or with POST https://api.past.dev/api/v1/projects/{slug}/keys and the management key. ## Claim Agent token: give the person the verification link that the claim_endpoint returns. The person signs in, reads a code on the page, and gives the code to the agent. The agent completes the claim with the code, stores the identity assertion, and exchanges it at the token endpoint for a short-lived access token. When the access token expires, exchange the assertion again. API key: sign in to the console at https://app.past.dev, pick the project in the header, and create a project key on the API keys screen. Store it as a secret. The examples use the environment variable PAST_API_KEY. The management key is created under Settings, Organization, Management key, by an Owner or Admin. ## Use the credential Send it on every request: ``` Authorization: Bearer $PAST_API_KEY ``` Each key is scoped to one project. The server derives the project from the key. Do not send projectId in a request. Call the API from a server: browser origins are refused by the CORS policy. The request and response contract is in https://past.dev/openapi.json. An agent access token is sent the same way, with the project named in a header: ``` Authorization: Bearer $ACCESS_TOKEN X-Past-Project: ``` Without X-Past-Project, the only live project of the organization is used. The scope memory:read opens recall, the ingestion status, the estimate, the identity reads, usage and the debugging reads. The scope memory:write opens ingest, batch ingest, retry, the deletion of an ingestion and the identity writes. The audience routes, the deletions by source id and the management routes take keys only. The page https://past.dev/docs/memory-api/authentication lists each route. ## Errors Every error is a JSON body with code, status, debugMessage, and data, except the per-minute rate limit, which answers 429 with no body. Every /api/v1 response also carries an X-Request-Id header. Authentication errors use 401: missing-api-key when no key is sent, malformed-api-key when the header or the key is not well formed, and unauthorized for an unknown, revoked or expired key and for a key of the kind a route refuses, where debugMessage names the kind. A key whose project is archived returns 403 project-archived. An agent access token that is invalid or expired returns 401 unauthorized, one without the scope of the route returns 403 insufficient-scope, one sent without X-Past-Project in an organization with two or more live projects returns 400 project-required, and an X-Past-Project that names no live project returns 404 project-not-found. An organization that is still being prepared returns 503 organization-not-ready. See the full table at https://past.dev/docs/memory-api/errors. ## Revocation Revoke a project key in the console or with DELETE https://api.past.dev/api/v1/projects/{slug}/keys/{keyId} and the management key. To rotate a key, mint a replacement and revoke the old key. The management key is rotated in the console. Contact support@past.dev if you cannot access the console. Revoked and expired keys return 401 unauthorized. For an agent token, the agent_auth block of the authorization server names the revocation_endpoint. An access token that is already issued works until it expires.