Authentication
Authenticate HTTP API requests with an organization API key or an OAuth access token.
Send one bearer credential on every POST /api/v1/* request:
Authorization: Bearer <credential>Organization API keys
An organization API key begins with aut_:
Authorization: Bearer aut_…The key selects its organization and currently receives every API scope. Per-key scope restriction is not part of HTTP API v1. Keep the key in your CI secret store and never put it in a request body or repository.
OAuth access tokens
A bearer token that does not begin with aut_ is verified as an OAuth access token. It must identify both a user and an organization, the user must still be a member of that organization, and it must carry the scope required by the operation.
| Scope | Access |
|---|---|
autonomy:read | Read Test Cases, Test Plans, Runs, External Evidence, Environments, and Notes |
autonomy:test_cases:write | Create Test Cases and replace their steps |
autonomy:test_plans:write | Create Test Plans and replace their membership |
autonomy:runs:write | Trigger Runs |
autonomy:environments:write | Create or update Environments; also required to relocate a credential-shaped Test Case value into an Environment secret |
autonomy:notes:write | Create Notes and comments |
The operation catalog names the exact scope for every route.
Authentication failures
A missing, malformed, expired, or invalid credential returns 401 with the UNAUTHENTICATED error. The response also includes a Bearer challenge:
WWW-Authenticate: Bearer resource_metadata="<SITE_URL>/.well-known/oauth-protected-resource/api/mcp"SITE_URL is the Autonomy application URL for the deployment, not the Convex site URL. OAuth clients can use the protected-resource metadata URL to discover the authorization server.