Clarify APIAuthentication
API keys for direct integrations and OAuth 2.0 for partners
Clarify supports two authentication methods:
- API keys: for backend services and scripts that work with a single workspace's own data.
- OAuth 2.0: for partner applications that act on behalf of users in other workspaces.
API keys
Create an API key in Settings → API Keys. There are two types:
- Personal: acts on your behalf and can access everything you can. Any workspace member can create one. This is the key to use for MCP.
- Workspace: a shared key, scoped to public data within the workspace. Only workspace admins can create one.
Send the key in the Authorization header using the api-key scheme, noting
that this is not a Bearer token:
Authorization: api-key YOUR_API_KEYA complete request:
curl https://api.clarify.ai/v1/workspaces/your-workspace/objects/person/resources \
-H "Authorization: api-key YOUR_API_KEY"Treat API keys like passwords: a personal key carries everything its creator can access. Store keys in an environment variable, never commit them to source control, and rotate them periodically.
OAuth 2.0
Partner integrations authenticate with OAuth 2.0 and act on behalf of a Clarify user. To register a client, contact support@clarify.ai with:
- A short description of your integration
- Whether your app is public or private (see below)
- One or more redirect URIs
- Optionally, an app logo for the consent screen (1:1 aspect ratio, at least 160×160px, JPG/PNG/SVG, max 100 KB; provide light and dark variants if you have them)
We'll send you a Client ID, plus a Client Secret for private apps.
Public vs private apps
- Private apps run on a server that can keep a secret. They use the Authorization Code flow and authenticate with their Client Secret.
- Public apps (native or single-page apps) can't safely store a secret. They
use the Authorization Code flow with PKCE (code challenge method
SHA-256) and must include theirclient_idin the token request body.
Endpoints
All OAuth endpoints live at auth1.clarify.ai:
| Purpose | Endpoint |
|---|---|
| Authorization | https://auth1.clarify.ai/oauth2/authorize |
| Token | https://auth1.clarify.ai/oauth2/token |
| Refresh token | https://auth1.clarify.ai/oauth2/token |
Scopes
Request scopes as a space-separated list:
openidprofileemailoffline_access: request this to receive a refresh token
Once you have an access token, send it in the Authorization header using the
standard Bearer scheme:
Authorization: Bearer ACCESS_TOKEN