# Authentication and API keys

> Authenticate REST and MCP calls safely with OTP ceremonies, bearer tokens, identity graphs, and scoped API keys.

Audiences: developers, agents
Kind: reference
Updated: 2026-07-17

Agreebase distinguishes authentication from signing. Authentication proves control of an Agreebase identity for access. Signing proves control for a specific record version and completes that participant's signature execution.

## REST bearer authentication

Request an authentication OTP through:

```http
POST /api/v1/verification/request-otp
Content-Type: application/json

{"email":"person@example.com","purpose":"authenticate"}
```

Verify the returned event with:

```http
POST /api/v1/verification/verify-otp
Content-Type: application/json

{"verification_event_id":"<event-id>","code":"123456"}
```

The response returns a short-lived bearer token. Send it as:

```http
Authorization: Bearer <token>
```

Authentication OTP, signature OTP, agreement-confirmation OTP, and contact-point linking OTP are separate purposes and cannot be substituted for one another.

## Hosted MCP connector OAuth

ChatGPT and Claude hosted custom connectors use `https://agreebase.com/mcp/oauth`. OAuth is the host-facing transport protocol; Agreebase identity remains an email contact point verified by OTP. The complete connection ceremony is:

```text
Connect → enter email → enter OTP → Verify and connect
```

The authorization page shows the requesting client, its exact registered redirect origin, the permissions, and the 90-day duration before the OTP is sent. Submitting the OTP through **Verify and connect** is explicit consent. Agreebase does not silently reuse a browser login.

The grant includes `create`, `retrieve`, `verify`, `amend`, `cancel`, and `offline_access`. Access tokens last one hour. Every refresh rotates the refresh token and remains bounded by the original 90-day grant expiry; refresh cannot extend the grant or add scopes. Disconnecting through the host invokes token revocation. Reusing a rotated refresh token revokes the whole connection.

OAuth authentication proves permission to operate tools as the verified contact-point identity. It never proves signature intent. An authentication OTP cannot satisfy a signature method, create signature evidence, enable `can_finalize`, or finalize a record. The user must complete a separate record/version-specific `signature_email_otp` or another configured signature method. OAuth also cannot activate API-key notarization `auto_seal`.

## API keys

API keys are long-lived integration credentials. Create them with a bearer-authenticated request to `POST /api/v1/api-keys`. The full key is returned once and cannot be retrieved later. Store it in a secret manager and send it as:

```http
X-API-Key: <agreebase-api-key>
```

List keys with `GET /api/v1/api-keys` and revoke one with `DELETE /api/v1/api-keys/{key_id}`. Revocation immediately prevents future authentication with that key.

## Exact scopes

Scopes are independent and must be granted explicitly:

| Scope | Main operations |
|---|---|
| `create` | Create agreements, declarations, and notarizations. |
| `retrieve` | Retrieve records, list records, and download PDFs/cards. |
| `verify` | Signature execution and verification-related participant actions. |
| `amend` | Amendments, participant invitation resends, witness replacement, and counters where applicable. |
| `cancel` | Declines, removals, rescission, draft cancellation, witness waiver, and cancellation records. |
| `offline_access` | Grants a refresh token so an OAuth connector can renew its access token without a fresh consent. OAuth-only; not issuable to API keys. |

Bearer sessions are live human sessions and are not API-key scope substitutes. The route's required scope is returned in the generated OpenAPI contract and in MCP errors such as `missing_scope`.

## Identity graph

An authenticated identity can have linked verified contact points. Use `GET /api/v1/identity/contact-points` to inspect them and `POST /api/v1/identity/link` to link a new verified email through a dedicated linking OTP ceremony.

The identity graph determines which records a person can retrieve and which participant identity an authenticated action represents. It does not make a person a signer: the participant still needs a finalized signature execution for the target record version.

## Direct/raw MCP authentication

For direct `/mcp`, begin with `get_authentication_status`. A transport `Authorization: Bearer` credential may be an API key or short-lived MCP authentication token. Without one, use `request_authentication_otp` and `verify_authentication_otp`.

The MCP OTP bootstrap grants only the `retrieve` scope and is intended for listing and reading records. Creation, signature execution, and lifecycle actions require a transport credential with the exact scope named by the MCP tool's `required_scopes` response. See the [MCP quickstart](/docs/developers/mcp-quickstart) for the complete session sequence and the [MCP reference](/docs/developers/mcp-reference) for the scope map.

When the client preserves MCP session state, the authenticated principal is bound to that session. When it cannot, verification can return a manual transport token valid for at most 600 seconds. Use it only in the immediate MCP `Authorization` header; do not store it in memory, prompts, logs, or notes.

## Security rules

- Never put an API key in a normal MCP tool argument.
- Never ask a user to paste a long-lived key into a chat transcript.
- For hosted connectors, let ChatGPT or Claude perform OAuth; do not request an API key or OTP inside the agent conversation.
- Do not log bearer tokens, refresh tokens, authorization codes, client secrets, API keys, transaction identifiers, or OTP codes.
- Treat OTPs as one-time, short-lived ceremony inputs.
- Check the exact returned scope instead of guessing a broader permission.