Authentication

Clarify supports two auth methods: API keys for direct integrations, and OAuth 2.0 for partner apps.

API key authentication

Creating an API key

Open your Clarify workspace
Go to Settings > API Keys
Click Create API key
Copy the key — you won't see it again

API keys have admin-level permissions to your workspace. They can read, write, and delete records. Sensitive fields like email bodies are redacted.

Using your key

curl -H "Authorization: api-key YOUR_API_KEY" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources"

The scheme is api-key, not Bearer — this is the most common mistake.

Security

Keys are scoped to a single workspace
Store them in environment variables, not source code
Rotate keys periodically in Settings > API Keys

export CLARIFY_API_KEY="your-key-here"

curl -H "Authorization: api-key $CLARIFY_API_KEY" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources"

OAuth 2.0

For partner integrations, Clarify supports Authorization Code and PKCE grants. Contact support@clarify.ai to get an OAuth app created for your integration.

Endpoints

Endpoint	URL
Authorization	`https://auth1.clarify.ai/oauth2/authorize`
Token	`https://auth1.clarify.ai/oauth2/token`
Refresh	`https://auth1.clarify.ai/oauth2/token`

Scopes

openid profile email offline_access

Flow

1. Get an authorization code:

GET https://auth1.clarify.ai/oauth2/authorize
  ?response_type=code
  &client_id={your_client_id}
  &scope=openid%20profile%20email%20offline_access
  &redirect_uri={your_redirect_url}

2. Exchange for tokens:

curl -X POST https://auth1.clarify.ai/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code={your_code}" \
  -d "redirect_uri={your_redirect_uri}" \
  -d "client_id={your_client_id}" \
  -d "client_secret={your_client_secret}"

3. Use the access token:

curl -H "Authorization: Bearer {access_token}" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources"

OAuth uses Bearer, not api-key. Only API key auth uses the api-key scheme.

Authentication

On this page