Authenticate an integration

Every REST and MCP request uses a bearer JWT. Alcarta issues the same JWT shape from a personal access token (PAT) or OAuth 2.1 authorization.

Personal access token

For a private or server-to-server integration:

1. Create an agent in the Alcarta web interface.

2. Give it mailbox grants.

3. Mint a token, optionally narrowing it with scopes.

4. Copy the returned JWT. It is shown once.

5. Send it in the Authorization header:

   Authorization: Bearer eyJhbGciOiJFZERTQSIs…

The token is revocable state, not a self-contained grant. Alcarta checks its tid, subject state, organization, and current grants after verifying its Ed25519 signature.

OAuth 2.1

Use OAuth for third-party applications that connect on behalf of an organization. Discovery is available at:

/.well-known/oauth-authorization-server
/.well-known/oauth-protected-resource/api/v1
/.well-known/oauth-protected-resource/mcp
/.well-known/jwks.json

The implemented server supports authorization code with PKCE, dynamic client registration, refresh-token rotation, token revocation, and a human consent screen. Consent materializes as an ordinary Alcarta agent and mailbox grants, so downstream authorization is identical to a PAT.

The protected resource differs by interface: ${BASE_URL}/api/v1 for REST and ${BASE_URL}/mcp for MCP. Request the resource you will call.

Handle authentication failures

An absent or invalid credential returns 401 with WWW-Authenticate: Bearer. Revoked, expired, or disabled credentials are not JSON-RPC tool errors on MCP; they stay at the HTTP layer so a client can restart its OAuth flow.

Treat 401 as a credential problem, 403 org_mismatch as the wrong organization binding, and 429 rate_limited according to Retry-After. Do not retry an invalid credential in a tight loop.

Token hygiene

• Never place a token in a URL or query parameter.
• Do not log the Authorization header.
• Use the narrowest useful token scopes.
• Rotate long-lived PATs and revoke the previous token after its grace period.
• Disconnect an OAuth application from organization settings when it should lose all consented access.