Authentication

API keys

• The person creates a key in Settings, under Advanced, while signed in. The full key is shown once. Store it then.
• Keys start with itk_. Only a hash is stored, so a lost key can't be shown again. Revoke it and make a new one.
• An API key can't create or revoke keys. Those calls return 403 owner_session_required.
• Trial accounts can have 1 active key. Pro accounts can have 3.
• A revoked key stops working on the next request.
• Never ask a person to paste a key into chat. Put it in your agent's config or secret store.

Send the key as a bearer token on every request:

Authorization: Bearer itk_...

A missing key gets a 401 with missing_api_key. A wrong or revoked key gets invalid_api_key:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"
{ "error": "invalid_api_key", "error_description": "This API key is invalid or was revoked. The account owner can create a new one in Settings > Advanced (https://getinboxtriage.com/settings)." }

On /mcp the 401 also has a WWW-Authenticate header that points to the OAuth metadata, so MCP clients can start sign-in:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://getinboxtriage.com/.well-known/oauth-protected-resource/mcp", scope="mcp:tools"
{ "error": "invalid_token", "error_description": "..." }

OAuth 2.1 for MCP (Connect)

MCP hosts such as Claude, ChatGPT, and Claude Code connect with OAuth. The person signs in to Inbox Triage and approves the agent. No key changes hands.

• Discovery: https://getinboxtriage.com/.well-known/oauth-protected-resource/mcp (RFC 9728) names the authorization server. https://getinboxtriage.com/.well-known/oauth-authorization-server (RFC 8414) lists the endpoints.
• Client registration: dynamic registration at POST /oauth/register (RFC 7591), or a client ID metadata document URL as the client_id. Redirect URIs must be on the allowlist: Claude, ChatGPT connector callbacks, or a loopback http://127.0.0.1:PORT/callback or http://localhost:PORT/callback.
• Authorization: GET /oauth/authorize with response_type=code, PKCE with code_challenge_method=S256 (required), and resource=https://getinboxtriage.com/mcp. Scope is mcp:tools.
• Tokens: POST /oauth/token with grant_type=authorization_code or refresh_token.
• Revocation: POST /oauth/revoke (RFC 7009) with token and client_id, authenticated the same way as the token endpoint. Revoking a refresh token also ends the access tokens from the same sign-in. The answer is 200 even for a token that is unknown or already revoked.
• Access tokens start with ita_ and last 1 hour. They only work on /mcp, not on /api.
• Refresh tokens start with itr_ and last 30 days. Each refresh returns a new refresh token and revokes the old one, so always store the newest.

Disconnecting agents

Settings lists connected agents. The person can disconnect one agent, or disconnect every agent and revoke every API key at once. A disconnected agent's tokens stop working and it has to Connect again.