Authentication

Coherence supports two authentication methods: API keys for server-to-server integration and OAuth 2.0 for user-authorized applications.

API Keys

When to Use

Use API keys for:

• Backend integrations
• Automated scripts
• Server-to-server communication
• Zapier and other automation tools

Creating an API Key

1. Go to Settings > API
2. Click Create API Key
3. Name your key (e.g., "Production Integration")
4. Set permissions
5. Copy and securely store the key

Using API Keys

Include the key in the Authorization header:

curl -X GET "https://api.getcoherence.io/v1/modules/contacts/records" \
  -H "Authorization: Bearer ck_live_abc123xyz789"

Key Prefixes

Key Permissions

Limit what each key can access:

Revoking Keys

To revoke an API key:

1. Go to Settings > API
2. Find the key
3. Click Revoke

Revocation is immediate - all requests using that key will fail.

OAuth 2.0

When to Use

Use OAuth for:

• Third-party applications
• User-installed apps
• Apps that act on behalf of users
• Public integrations

OAuth Flow

1. Redirect to authorization URL
2. User grants permission
3. Receive authorization code
4. Exchange for access token
5. Use token for API requests

Authorization URL

https://app.getcoherence.io/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read write

Token Exchange

Exchange the authorization code for tokens:

curl -X POST "https://api.getcoherence.io/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback"

Response:

{
  "access_token": "at_abc123...",
  "refresh_token": "rt_xyz789...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Using Access Tokens

curl -X GET "https://api.getcoherence.io/v1/users/me" \
  -H "Authorization: Bearer at_abc123..."

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token:

curl -X POST "https://api.getcoherence.io/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=rt_xyz789..."

OAuth Scopes

Security Best Practices

API Key Storage

Do:

• Store keys in environment variables
• Use secret management services
• Rotate keys regularly

Don't:

• Commit keys to source control
• Share keys in plain text
• Use production keys in development

Token Storage

For OAuth tokens:

• Store tokens encrypted
• Use secure, httpOnly cookies for web apps
• Implement secure storage for mobile apps

IP Restrictions

Limit API key usage by IP:

1. Go to API key settings
2. Add allowed IP addresses
3. Requests from other IPs will fail

Audit Logging

Monitor API usage:

• View request logs in Settings
• See which keys are active
• Track rate limit usage

Error Handling

Authentication Errors

Example Error

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided",
    "status": 401
  }
}

Testing Authentication

Verify Your Key

Test your API key:

curl -X GET "https://api.getcoherence.io/v1/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "data": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "Your Name"
  }
}

Related: API Overview