Authentication

Agent Memory accepts two kinds of bearer credentials on the data plane (/v1) and the MCP endpoints:

Both are sent the same way:

Authorization: Bearer <credential>

Requests without a valid credential get 401. A valid credential without the required capability gets 403; a workspace it doesn't hold gets 404.

API keysCopy Anchor Link

Creating a keyCopy Anchor Link

In the web console, open API Keys → Create API Key and choose:

• the project (workspace) and, optionally, an application — an application-scoped key always targets that application plus the workspace-wide pool, and requests cannot override it;
• the capabilities (below);
• the agents the key may act as — the first is the key's default agent;
• whether the key may act for users (name end users with userId);
• an optional expiry.

The key is shown once. Only its SHA-256 hash and a short display prefix (amk_ plus 8 characters) are stored, so a database leak never yields usable keys. Programmatic minting is available through the provisioning API, and self-hosted operators can mint the first key from the command line with --bootstrap-key (see Deployment).

CapabilitiesCopy Anchor Link

Each endpoint's required capability is listed in the API reference. Grant the minimum: a recall-only service needs only read.

Agent bindingCopy Anchor Link

Every key is bound to the agent IDs chosen at creation. Requests that omit agentId act as the default agent; naming an unbound agent is refused with 403 policy_denied. A key created with no agent IDs acts only as itself. See Identity and visibility.

Revocation and expiryCopy Anchor Link

Revoking a key (console, or DELETE /api/control/keys/{keyId}) takes effect on the next request on every API replica — key lookups are cached in a shared cache that revocation invalidates. Expired keys stop authenticating automatically.

OAuth for MCP clientsCopy Anchor Link

When a deployment enables its built-in OAuth 2.1 authorization server, MCP clients can connect with nothing but a URL:

1. The client calls the MCP endpoint without a token and receives 401 with a WWW-Authenticate header pointing at the protected-resource metadata (/.well-known/oauth-protected-resource, RFC 9728).
2. The metadata names the authorization server; the client discovers it (/.well-known/oauth-authorization-server or /.well-known/openid-configuration) and registers itself dynamically (/connect/register).
3. A browser window opens, the user signs in with their Agent Memory account, and the client receives tokens through the authorization-code flow (/connect/authorize, /connect/token).

Signing in never creates an account: a person without an Agent Memory account is told to finish sign-up in the console first. The token resolves to the person's console account and the workspaces they have grants on. Self-hosted operators configure the server with the OAuth:* keys — see Configuration.

Console sign-inCopy Anchor Link

The web console (/app/) supports sign-in with Google, Microsoft (OpenID Connect) and one-time email codes, depending on what the deployment configures. Organizations can require MFA-verified sign-ins for console access with the tenant setting security.requireMfa. Console sessions are separate from API credentials: agents always use keys or OAuth tokens.

Choosing a credentialCopy Anchor Link