Authentication

The v1 API accepts two credential types: personal API keys (issued to a single user inside a single organization) and OAuth 2.0 bearer tokens (issued to third-party apps acting on behalf of a user).

API keys

Create keys at Settings → API Keys in your dashboard. Each key is scoped to a single organization and has its own scope list. Keys are revealed once at creation; copy and store immediately.

curl https://www.clientcasa.com/api/v1/clients \
  -H "x-api-key: sk_live_xxxxxxxxxxxx"

You can also send keys as a Bearer token:

curl https://www.clientcasa.com/api/v1/clients \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

OAuth 2.0 (third-party apps)

For partners that need to act on behalf of users (Zapier-class integrations), use the OAuth 2.0 authorization-code flow with PKCE. Register an app at Settings → OAuth Apps, then direct users through:

• GET /api/auth/oauth2/authorize?client_id=…&response_type=code&redirect_uri=…&scope=…&code_challenge=…
• POST /api/auth/oauth2/token to exchange the code for an access token

Access tokens are JWTs valid for 1 hour. Refresh tokens are valid for 30 days. The organizationId is stamped into the access token's claims at consent time — every request acts on that organization.

curl https://www.clientcasa.com/api/v1/clients \
  -H "Authorization: Bearer eyJhbGc..."

Scopes

Both credential types use the same scope vocabulary. A scope of <resource>:<action> (e.g. clients:read, invoices:write) grants access to one resource. The same scope can be written <action>:<resource> (read:clients, write:invoices) — both forms are accepted by the API.

A request without the required scope returns 403 forbidden.