Build a multi-tenant integration with OAuth 2.1
Let your users connect their own Crisphive business to your product — OAuth 2.1 with a consent screen, no API key ever copied.
API keys authenticate your own business. When you build a product that other Crisphive businesses plug into — a CRM sync, a booking widget, an AI-agent connector — use the built-in OAuth 2.1 Authorization Server instead: each business owner approves your app on a consent screen, and your app receives tokens bound to their tenant.
/v1 API and the /mcp endpoint. Send Authorization: Bearer <access_token> exactly like an API key.The flow
The server implements the current OAuth 2.1 draft: PKCE (S256) is required, and registration is dynamic — no manual app-review step. Self-registered clients are public (no secret); partner platforms such as Zapier and Make use a client id and secret issued by Crisphive, and only those are shown as Verified on the consent screen:
| Step | Request |
|---|---|
| 1. Discover the AS | GET /.well-known/oauth-authorization-server (RFC 8414) → endpoint URLs, supported grants |
| 2. Register | POST /oauth/register (RFC 7591 Dynamic Client Registration) → client_id |
| 3. Authorize | GET /oauth/authorize?… — the business owner signs in to Crisphive and consents |
| 4. Exchange | POST /oauth/token (grant_type=authorization_code, code, code_verifier) → { access_token, refresh_token, expires_in } |
| 5. Refresh | POST /oauth/token (grant_type=refresh_token) → a rotated token pair (the old refresh token is single-use) |
Tokens
The token is bound to the consenting owner’s business, region, and environment — it can never reach another tenant or flip live↔sandbox. The token acts as the person who approved it: every call is checked against that member’s current role, so the app can never do more than they could in the dashboard, and it stops working if they are removed or suspended. Request a narrower scope (space-separated permission codes, e.g. customers_view job_view) to limit it further; omitting it means everything that member may do. A scope the member does not hold is refused at consent. Access tokens live ~1 hour; refresh with the single-use refresh token to stay connected.
Connection lifetime
A connection is governed by two independent clocks. An integration in daily use is never disconnected on a schedule; one that is forgotten expires on its own.
- Idle window — 30 days. Every token refresh issues a new refresh token good for another 30 days. Keep using the connection and it rolls forward indefinitely; go quiet for 30 days and it lapses.
- Absolute cap — 90 days. Regardless of activity, a connection ends 90 days after the business owner approved it. The business can set this to anything from 1 to 365 days per connection under Developers → MCP connections; the countdown is measured from the original approval, not from the change.
When either clock runs out, refreshing fails (OAUTH_GRANT_EXPIRED) and the owner must approve the app again from the consent screen. Treat any failed refresh as “restart the authorization flow”, never as a retryable error. The business’s Owners and Administrators are emailed 14 days before a connection expires — re-approving needs the owner in a browser, so the warning comes earlier than for keys.
Calling the API
curl "https://api.crisphive.com/v1/customers" \ -H "Authorization: Bearer <access_token>"
Building an AI-agent connector instead? The MCP server uses this exact flow — compliant MCP clients run it automatically, so you normally write no OAuth code at all.