# Authentication for agents

> How an autonomous agent obtains, uses and revokes credentials for the Explorium API and MCP server.

## Discover

Explorium exposes two authenticated surfaces:

- **REST API** — `https://api.explorium.ai`, described by the OpenAPI document at https://api.explorium.ai/openapi.json.
- **MCP server** — `https://mcp.explorium.ai/mcp`, Streamable HTTP transport, described by the server card at https://www.explorium.ai/.well-known/mcp/server-card.json.

Machine-readable entry points:

- API catalog (RFC 9727): https://www.explorium.ai/.well-known/api-catalog
- ARD capability catalog: https://www.explorium.ai/.well-known/ai-catalog.json
- Agent skills index: https://www.explorium.ai/.well-known/agent-skills/index.json
- A2A agent card: https://www.explorium.ai/.well-known/agent-card.json

## Pick a method

| Surface | Method | Credential | Sent as |
| --- | --- | --- | --- |
| REST API | API key | Long-lived key issued per account | `api_key` request header |
| MCP server | OAuth 2.0 | Access token from the authorization flow | `Authorization: Bearer <token>` |

Use the API key for server-to-server automation. Use OAuth when the agent runs inside an MCP client (Claude, ChatGPT, an IDE assistant) that can complete an interactive authorization step on behalf of a user.

## Register

Registration is account-based and human-mediated. There is no automated client-registration endpoint: Explorium does not currently publish an `agent_auth` block, and therefore advertises no `register_uri`, `claim_uri` or `revocation_uri`. Agents should not attempt dynamic registration, and should not expect `identity_assertion` or `id-jag` token exchange to be available.

To obtain credentials:

1. Create an account at https://www.explorium.ai/sign-up/ (a free trial with 100 credits is available).
2. Open the admin console at https://admin.explorium.ai.
3. Generate an API key from the console — see https://developers.explorium.ai/reference/setup/getting_your_api_key for how keys are issued and scoped.

## Claim

For the REST API, the key generated in the console is the credential — there is no separate claim step.

For the MCP server, connect an MCP client to `https://mcp.explorium.ai/mcp`. The server responds to `initialize` with an OAuth authorization challenge; the client completes the flow and stores the resulting access token. The token is scoped to the authorizing account and its credit balance.

## Use the credential

REST request:

```http
POST /v1/businesses/match HTTP/1.1
Host: api.explorium.ai
Content-Type: application/json
api_key: <your-api-key>
```

MCP request:

```http
POST /mcp HTTP/1.1
Host: mcp.explorium.ai
Authorization: Bearer <access-token>
```

Start here: https://developers.explorium.ai/reference/quick-starts/quick-starts

## Errors

- **401** — the credential is missing, malformed or expired. The MCP endpoint answers with a `WWW-Authenticate: Bearer` challenge. Re-run the authorization flow; do not retry with the same token.
- **403** — authenticated but not entitled to the requested data or operation.
- **429** — rate limited. Honour `Retry-After` and back off. See https://developers.explorium.ai/reference/rate-limit.
- **Credit exhaustion** — operations fail once the account's credit balance is spent. Check remaining balance in the console before large batch runs, and use cost estimation before exporting.

## Revocation

Revoke an API key by deleting it in the admin console at https://admin.explorium.ai; revocation takes effect immediately and any agent still presenting the key receives 401. Revoke MCP access by disconnecting the Explorium connector in the MCP client, which discards the stored token. To revoke everything for an account, contact https://www.explorium.ai/contact-us/.

## Handling credentials

Treat API keys as secrets: keep them in environment variables or a secret manager, never in source control, client-side code or logs. Keys are account-scoped and carry the account's full entitlements.