# How agents authenticate to Automo

This is the agent_auth walkthrough for Automo. Humans can follow https://automo.ai/developers. The identity_endpoint and authorization server live on https://mo.automo.ai, not on the marketing site.

## Discover

Start at this file, then read:

- Apex pointer: https://automo.ai/.well-known/oauth-authorization-server (issuer is https://mo.automo.ai)
- Live RFC 8414 metadata: https://mo.automo.ai/.well-known/oauth-authorization-server
- Protected resource (RFC 9728): https://mo.automo.ai/.well-known/oauth-protected-resource/mcp
- OpenAPI: https://automo.ai/openapi.json
- MCP server: https://mo.automo.ai/mcp

Unauthenticated POST https://mo.automo.ai/mcp returns 401 with WWW-Authenticate naming the resource_metadata URL. That header is the signpost, not a dead end.

## Pick a method

Supported method: OAuth 2.0 authorization code with PKCE S256 (service_auth for a user who signs in and consents). There is no API-key path and no identity_assertion / id-jag path yet.

code_challenge_methods_supported is S256 only.

## Register

POST https://mo.automo.ai/oauth/register (RFC 7591). No prior credential. The response includes client_id (and client_secret when the server issues one). token_endpoint_auth_methods_supported: none, client_secret_post.

## Claim

Send the person to GET https://mo.automo.ai/oauth/authorize with response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, and optional scope and state. They sign in to Automo and consent to scopes for one workspace.

## Exchange

POST https://mo.automo.ai/oauth/token with grant_type=authorization_code, code, redirect_uri, client_id, and code_verifier. The response is an access_token and a refresh_token (offline_access).

## Use the access_token

POST https://mo.automo.ai/mcp with Authorization: Bearer {access_token} and a JSON-RPC MCP body. Tool calls act as the connected Automo user in the consented workspace.

## Errors

- 401 on /mcp: missing or invalid token. Follow WWW-Authenticate resource_metadata.
- 400 invalid_grant on /oauth/token: code already used, expired, or PKCE mismatch.
- 400 invalid_request: missing fields.
- 405 on GET /mcp: use POST.

## Revocation

Refresh tokens stop working when the person disconnects the assistant in Automo Settings, or when they revoke the client. Request a new authorization if the token endpoint returns invalid_grant on refresh.