Authentication

Contact Button accepts Laravel Sanctum bearer tokens. Store tokens in a server-side secret manager and send them with every authenticated request.

Authorization: Bearer <access-token>

Create a key in the portal

Humans can create a scoped key from Account → API Keys in the Contact Button portal, or open app.contactbutton.com/account/api-keys directly. Name the key for the agent or integration that will store it, select only the permissions it needs, and choose an expiration. New keys default to the Read only preset (workspaces:read and content:read). Choose Build and publish only when the agent must configure workspaces or change content, Manage leads only when it must access submissions and conversations, or Custom for a narrower combination. Lead access, writes, and protected action requests are never selected by default. The secret is displayed once. Copy it directly into the coding-agent host’s secret manager or store it as CONTACTBUTTON_TOKEN; never paste it into a prompt or chat transcript. The same page shows when each key was last used and lets the human rotate or revoke it at any time. Rotation revokes the previous secret immediately. Portal keys act as the signed-in human and can reach only the workspaces that human can access. Scopes narrow that access further:

Scope	Grants
`workspaces:read`	Read workspaces, teams, domains, settings, and connections
`workspaces:write`	Create and manage workspaces, teams, domains, settings, and connections
`content:read`	Read buttons, forms, lists, pages, booking types, and knowledge content
`content:write`	Create, update, publish, and remove content
`engagements:read`	Read submissions, subscribers, bookings, callbacks, calls, reviews, and conversations
`engagements:manage`	Reply to and manage engagement records
`actions:request`	Request protected actions that still require human confirmation

An agent can start setup without a browser. Contact Button emails a six-digit code to the represented human, then returns a scoped token after verification.

curl -X POST https://api.contactbutton.com/v1/signups \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: signup-acme-assistant-01' \
  -d '{"human_email":"owner@example.com","display_name":"Acme setup agent","token_name":"acme-agent"}'

Verify with the code delivered to the human:

curl -X POST https://api.contactbutton.com/v1/signups/{signup_id}/verify \
  -H 'Content-Type: application/json' \
  -d '{"otp_code":"123456"}'

The issued token includes workspace, content, engagement-inbox, and action-request abilities. Tokens never grant permission to skip a represented human’s confirmation for a subscription, booking, or callback.

Idempotency

Send an Idempotency-Key of 8–120 safe characters on mutations. Repeating the same method, path, and body returns the stored response with Idempotency-Replayed: true. Reusing the key with different input returns 409 Conflict.

Errors and request tracing

API v1 errors use application/problem+json and include a stable code, a safe resolution, and an X-Request-ID header. Provide your own opaque request ID to correlate a workflow across systems. See API errors for the complete contract.

OAuth status

Server integrations may continue to use scoped API keys. Interactive MCP clients use registered OAuth applications with Authorization Code + PKCE, short-lived access tokens, refresh tokens, and explicit workspace grants. Register the client in API Keys, use the published /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server metadata, and send the canonical MCP resource indicator. Unrestricted dynamic client registration is disabled, and MCP OAuth tokens are not general-purpose REST credentials.

Get started

Build

Operate

Create a key in the portal

Idempotency

Errors and request tracing

OAuth status

​Create a key in the portal

​Agent-first signup

​Idempotency

​Errors and request tracing

​OAuth status

Create a key in the portal

Agent-first signup

Idempotency

Errors and request tracing

OAuth status