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:
POST /api/v1/verification/request-otp
Content-Type: application/json
{"email":"person@example.com","purpose":"authenticate"}
Verify the returned event with:
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:
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:
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:
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 for the complete session sequence and the 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.