# Momentic agent authentication

Momentic is an AI end-to-end testing platform for web, iOS, and Android. This
file tells an agent how to get a credential, use it, and revoke it. The
equivalent pages for humans are the [API reference](https://momentic.ai/docs/api-reference/overview) and
[API keys and team](https://momentic.ai/docs/account/api-keys-and-team).

## Discover

- Public REST API: `https://api.momentic.ai`
- OpenAPI 3.0 description: https://momentic.ai/docs/api-reference/openapi.json
- API catalog (RFC 9727): https://momentic.ai/.well-known/api-catalog
- Hosted MCP endpoint: `https://api.momentic.ai/mcp` (streamable HTTP, POST only)
- MCP protected resource metadata: https://api.momentic.ai/.well-known/oauth-protected-resource/mcp
- OAuth authorization server metadata: https://api.momentic.ai/.well-known/oauth-authorization-server
- Agent instructions: https://momentic.ai/agents.md
- Site index for agents: https://momentic.ai/llms.txt

There is no `agent_auth` block, no `identity_assertion` flow, and no
`id-jag` token exchange.

## Pick a method

There are two methods, one for each surface.

For the REST API, use a long-lived API key as an HTTP bearer token. Keys belong
to an organization, not to an agent identity. An agent cannot mint its own key.
A human creates the key and gives it to the agent.

For the hosted MCP endpoint, use OAuth 2.1 with PKCE against
https://auth.momentic.ai. The MCP client reads the metadata documents above,
registers itself at the `registration_endpoint`, and a person approves the
request in a browser. The endpoint exposes the `momentic_list_runs` and
`momentic_quarantine_list` tools. An API key does not work here, and an OAuth
access token does not work on the REST API.

## Register

Create a Momentic account at https://app.momentic.ai/signup. The Free plan includes monthly
credits and needs no credit card. A person must do this step in a browser,
because Momentic has no API for account creation.

## Claim

A member of the organization opens https://app.momentic.ai/settings/api-keys and creates an API key. Copy
the key at creation time; Momentic shows the secret once. Store it as the
`MOMENTIC_API_KEY` environment variable, which is the name the Momentic CLI
and the local MCP server read (see [MCP server](https://momentic.ai/docs/coding-agents/mcp-server)).

## Use the credential

Send the key in an `Authorization` header on every request:

```bash
curl "https://api.momentic.ai/v1/runs?pageSize=20" \
  -H "Authorization: Bearer $MOMENTIC_API_KEY"
```

Scope and limits of the current public endpoints:

- `GET /v1/runs` and `GET /v1/run-groups` return completed runs only.
- Every response is scoped to the organization that owns the key.
- The endpoints are read-only: no public endpoint writes data, so no
  idempotency key is needed.
- Lists use cursor pagination. Pass `pageSize` (max 100) and send the returned
  `nextCursor` back as `cursor`.
- A `startDate`/`endDate` window may not exceed 92 days.

## Errors

| Status | Body                                                 | What to do                                    |
| ------ | ---------------------------------------------------- | --------------------------------------------- |
| 401    | `Missing token` (plain text)                         | Send the `Authorization: Bearer <key>` header |
| 401    | `{"error": "Missing API key"}`                       | The header has no key after `Bearer`          |
| 403    | `{"error": "Invalid API key"}`                       | The key is wrong or revoked; use a new key    |
| 400    | `{"error": "Invalid query: <detail>"}`               | Fix the query parameter                       |
| 400    | `{"error": "Date window must not exceed 92 days."}`   | Narrow the date window                        |
| 400    | `{"error": "Invalid cursor."}`                       | Restart from the first page                   |
| 429    | `Too many requests, please try again later.` (plain text) | Wait, then retry with fewer requests     |
| 503    | `{"error": "We encountered a temporary error validating your API key."}` | Retry the request         |

Most bodies are JSON with an `error` string, but the two plain-text rows above
are not. Parse the body as JSON, and fall back to the raw text if that fails.
Rate-limited responses also carry the `RateLimit-Limit`,
`RateLimit-Remaining`, and `RateLimit-Reset` headers. A REST 401 carries no
`WWW-Authenticate` challenge.

The hosted MCP endpoint uses a different error shape. It answers a request with
no token with a 401, a `WWW-Authenticate: Bearer` challenge that points to the
protected resource metadata, and a JSON body with an `error` and an
`error_description` field.

Cursors are opaque. Do not build or parse one.

## Revocation

Delete the key at https://app.momentic.ai/settings/api-keys. Deletion takes effect immediately, and a
later request with that key gets a 403. To rotate a key, create the new key
first, move your agents to it, then delete the old key. An agent cannot revoke a
key through the API.