# GetRecited agent authentication

## Discover

Read [the OpenAPI contract](https://getrecited.com/openapi.json) and [protected-resource metadata](https://getrecited.com/.well-known/oauth-protected-resource). The supported methods are a workspace API key and OAuth 2.0 client_credentials. Read [authorization-server metadata](https://getrecited.com/.well-known/oauth-authorization-server). WorkOS agent_auth registration, identity_assertion, service_auth and id-jag exchange are not implemented. There is no identity_endpoint, claim_endpoint or events_endpoint to advertise.

## Pick a method

Send Authorization: Bearer followed by your ctx_ key. X-Api-Key is also supported by REST. MCP requires a manually configured workspace key in the Bearer header; it does not accept REST OAuth tokens or advertise MCP OAuth discovery. Keep keys in a server-side secret store or local environment; never paste them into an agent conversation, source control or browser storage.

## Register

Sign in to your existing GetRecited account and select the workspace you administer. Early-access availability and API entitlement depend on your account; this is not automatic agent registration. The public index and documentation require no account.

## Claim

Workspace administrators control API keys. An agent cannot claim an organization, domain or identity merely by providing a URL. User authorization is required before an integration accesses workspace data.

## Exchange

Open Settings → Developer and create a named API key. Copy it once, store it securely and grant only the required scopes: read:brands, read:visibility or read:scans. For OAuth client_credentials, POST form-encoded grant_type=client_credentials, client_id (the first 12 characters of your key), client_secret (the full key), and optional space-separated scope to https://getrecited.com/oauth/token. HTTP Basic client authentication is also supported. The response includes access_token, token_type=Bearer, expires_in=900 and scope. Requested scopes must be a subset of your key permissions; no refresh token is issued. Keep this confidential-client exchange on your own server.

## Use the access_token

For REST, send either the workspace key or the OAuth access_token as a Bearer credential. Tokens expire after 15 minutes, remain bound to their issuing key and cannot elevate its scopes. For example:

```sh
curl --fail-with-body https://getrecited.com/api/v1/brands \
  -H "Authorization: Bearer $GETRECITED_API_KEY"
```

The read API returns JSON; /mcp exposes the same reads through Streamable HTTP. Brand-scoped MCP credentials cannot be used as workspace REST keys.

## Errors

401 means missing, invalid, revoked or wrong-kind key. WWW-Authenticate includes a Bearer resource_metadata URL. 403 means the scope is missing. 404 also covers a brand unavailable in your workspace. 422 means invalid parameters. 429 includes Retry-After; wait that long before retrying. JSON errors contain code, message and request_id. A 503 means a dependency is unavailable. Do not log the credential when reporting a failure.

## Revocation

Revoke the key in Settings → Developer, then remove it from your integration. Rotation requires creating a replacement key and revoking the old one. Revoked or expired keys, and all OAuth tokens issued from them, fail verification on subsequent requests. Reducing key scopes also reduces the effective token scopes. Read [developer guidance](https://getrecited.com/developers.md) for SDKs and local testing.