Authentication

The CaseHug API supports two authentication methods: API Keys for server-to-server integrations, and OAuth 2.0 for integrations that act on behalf of firm users.

API Key Authentication

The simplest way to authenticate. Pass your API key in the X-Api-Key request header. API keys are scoped to specific resources and operations.

⚠️

Keep your API key secret. Never expose it in client-side code or public repositories. Use environment variables and server-side code only.

API Key Request

curl -X GET https://api.calmintake.com/api/v1/matters \
  -H "X-Api-Key: ch_live_sk_abc123xyz" \
  -H "Content-Type: application/json"

Available Scopes

Scope	Description
matters:read	List and retrieve matters
matters:write	Create, update, and archive matters
clients:read	List and retrieve clients
clients:write	Create and update clients
documents:read	List and retrieve documents
documents:write	Request, approve, and manage uploads
webhooks:read	List webhook endpoints
webhooks:write	Create, update, and delete webhooks
firms:read	Read firm details and settings
firms:write	Update firm settings and manage users

Code Examples

curl -X GET https://api.calmintake.com/api/v1/matters \
  -H "X-Api-Key: ch_live_sk_abc123xyz" \
  -H "Content-Type: application/json"

OAuth 2.0

Use OAuth 2.0 when your integration needs to act on behalf of a specific firm user. CaseHug supports the Authorization Code flow.

Step 1 — Redirect to Authorization

Authorization URL

https://app.calmintake.com/oauth/authorize
  ?client_id=your_client_id
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=matters:read+clients:read
  &state=random_state_string

Step 2 — Exchange Code for Token

Token Request

POST /oauth/token HTTP/1.1
Host: api.calmintake.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_REDIRECT
&redirect_uri=https://your-app.com/callback
&client_id=your_client_id
&client_secret=your_client_secret

Token Response

{
  "access_token": "ch_oauth_eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ch_refresh_eyJhbGciOiJSUzI1NiJ9...",
  "scope": "matters:read matters:write clients:read"
}

Step 3 — Use the Token

Authenticated Request

curl -X GET https://api.calmintake.com/api/v1/matters \
  -H "Authorization: Bearer ch_oauth_eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json"

Token Refresh Flow

Access tokens expire after 1 hour. Use the refresh token to get a new access token without requiring the user to re-authorize.

Refresh Token Request

POST /oauth/token HTTP/1.1
Host: api.calmintake.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=ch_refresh_eyJhbGciOiJSUzI1NiJ9...
&client_id=your_client_id
&client_secret=your_client_secret

Rate Limits

Rate limits are applied per API key per minute. Responses include headers showing your current usage.

Plan	Rate Limit	Burst
Standard	100 req/min	150 req/min for 10s
Pro	500 req/min	750 req/min for 10s
Enterprise	1,000 req/min	Custom

Rate Limit Headers

Header	Description
X-RateLimit-Limit	Total requests allowed per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when window resets
Retry-After	Seconds to wait before retrying (429 only)

429 Response

Rate Limit Exceeded

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709856000
Retry-After: 47

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 47 seconds.",
    "details": {
      "limit": 100,
      "window": "60s",
      "reset_at": "2024-03-07T14:00:00Z"
    }
  }
}

Auth Error Codes

Status	Code	Description
401	missing_api_key	No X-Api-Key header provided
401	invalid_api_key	API key is malformed or does not exist
401	expired_token	OAuth access token has expired
403	insufficient_scope	API key lacks required scope for this action
403	firm_suspended	Firm account is suspended
429	rate_limit_exceeded	Too many requests, see Retry-After header