# omnimatch.ai auth.md

How AI agents register with and authenticate to Omnimatch Agents (https://omnimatch.ai).

## Who this is for

Agents that want to call the REST API (https://omnimatch.ai/openapi.json) or the MCP server
(`https://omnimatch.ai/mcp`) on behalf of a user.

## Option 1 — OAuth 2.0 (recommended for agents)

1. Discover the authorization server: `https://omnimatch.ai/.well-known/oauth-authorization-server`
   (issuer, authorization/token endpoints, JWKS, grant types).
2. Register a client dynamically (RFC 7591): `POST https://omnimatch.ai/api/auth/mcp/register`
   with your `redirect_uris`. Anonymous registration is allowed;
   `token_endpoint_auth_method` may be `none` for public clients.
3. Run the authorization-code flow with PKCE (S256). Scopes: `openid profile email offline_access`.
4. Send the access token as `Authorization: Bearer <token>`.

Protected-resource metadata (RFC 9728): `https://omnimatch.ai/.well-known/oauth-protected-resource/mcp`.

## Option 2 — one-time connect code

For harnesses without MCP OAuth, a signed-in user copies a one-time connect code
from the web app (prefix `omc_`, valid 15 minutes, single use) and hands it to
their agent. The agent exchanges it for a scoped key:

```
POST https://omnimatch.ai/api/connect/exchange
Content-Type: application/json

{"code": "omc_...", "client": "<short name for this tool>"}
```

The response is `{"token": "oma_...", "mcpUrl": "..."}`. Send that token as
`Authorization: Bearer oma_...` on the MCP endpoint or the REST API. The minted
token is per-client and scoped to working with the user's agents (chat, search,
manage agents); it can't touch API keys, billing or account settings. The user
sees each connected client in the web app and can revoke them individually.

## Option 3 — user-provisioned API key

A signed-in user can create a long-lived API key in the web app (Settings → API
keys) and hand it to their agent. Send it as `Authorization: Bearer oma_...` on
both the REST API and the MCP endpoint.

## Credential use

- Bearer header only (`bearer_methods_supported: ["header"]`) — never in query strings.
- Tokens are per-user: an agent acts as the user who authorized it, with that
  user's subscriptions and spend caps.
- Revoke: users can revoke connected clients and API keys in the web app; OAuth
  clients lose access when the user signs out of the grant.

## More

- API docs: https://omnimatch.ai/docs
- MCP server card: https://omnimatch.ai/.well-known/mcp/server-card.json
- Agent skills: https://omnimatch.ai/.well-known/agent-skills/index.json