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>A credential that starts with aut_ is an organization API key. Anything else is checked as an OAuth access token.
Organization API keys
Use an API key for CI jobs, scripts and other systems that don't act as a person.
- Open Organization → API keys. Only owners and admins can manage keys.
- Under Create a key, enter a Key name, such as "GitHub Actions", and click Generate key.
- Copy the key right away. The dashboard shows it once: "Copy this key now. You won't see it again."
Authorization: Bearer aut_…What a key can do:
- It belongs to one organization and reaches every project in it.
- It has every scope below. There is no scope picker and no expiry date.
- It can send 1,000 requests per hour.
- It works on the HTTP API only. AI assistants connect to MCP with OAuth instead.
The API keys table lists each key by name, the start of the key and when it was created. To stop a key, click Revoke key: anything using it stops working immediately. Keep keys in your CI secret store, never in a request body or a repository.
OAuth access tokens
An OAuth access token acts as the person who authorized it, in one organization. It's what MCP clients use, and the HTTP API accepts it too. The person must still be a member of that organization, and a member reaches only the projects they can open. Owners and admins reach every project.
Access tokens last one hour. A client that asked for offline_access can refresh its token without asking you again.
Scopes
Each operation needs one scope. API keys have all of them. An OAuth token has the scopes approved on the consent screen.
| Scope | Consent screen wording | Operations |
|---|---|---|
autonomy:read | Read projects, test cases, runs and issues | Every list and get operation, run.step_actions and run.evidence |
autonomy:test_cases:write | Create and edit test cases | test_case.create, test_case.update_steps, test_case.archive |
autonomy:test_plans:write | Create and edit test plans | test_plan.create, test_plan.set_members |
autonomy:runs:write | Start runs | run.trigger |
autonomy:environments:write | Create and edit environments | environment.upsert |
autonomy:issues:write | File and update issues | issue.create, issue.comment, issue.set_status |
A token without the scope an operation needs gets 403 FORBIDDEN with the message "This operation requires the <scope> scope." and the scope in details.scope. The operation catalog names the scope of every operation.
Authentication failures
A missing, malformed, expired or invalid credential returns 401 with the UNAUTHENTICATED error:
1{2 "error": {3 "code": "UNAUTHENTICATED",4 "message": "Missing or invalid programmatic credentials."5 }6}The response also carries a Bearer challenge that OAuth clients use to find the authorization server:
WWW-Authenticate: Bearer resource_metadata="https://app.autonomyqa.com/.well-known/oauth-protected-resource/api/mcp"Didn’t find it?