Authentication

Every request to /api/v1 must carry an API key. Requests without one are rejected with 401 and error.code of UNAUTHORIZED.

Create keys in Settings → API Keys. A key is shown once at creation.

Sending a key

Two headers work, and they are equivalent — use whichever fits your HTTP client.

As a bearer token:

curl https://clientsphere.io/api/v1/contacts \
  -H "Authorization: Bearer sk_live_your_key_here"

Or as a dedicated header:

curl https://clientsphere.io/api/v1/contacts \
  -H "X-API-Key: sk_live_your_key_here"

When a key is rejected

All three rejections are 401, and the code tells you which problem you have:

INVALID_KEY covers three cases, and the message distinguishes them:

• The key is not one we issued, or has been deactivated in Settings → API Keys. This is by far the most common cause — check the key still exists and is active before looking anywhere else.
• The key was truncated or mistyped in transit.
• The prefix does not match the key's mode. A key is created as either test or live and its prefix reflects that: sk_test_ or sk_live_. The prefix is not decoration — the API checks it against the key's own mode and rejects a mismatch, telling you which way round it went.

Keys can expire

A key may be given an expiry date when it is created. Past that moment it stops working and returns 401 KEY_EXPIRED — the key is not deleted, so it is still listed in Settings → API Keys, which is what makes this one easy to misdiagnose as a permissions problem.

Keys without an expiry date do not expire. If an integration fails at a suspiciously round moment, check the expiry before anything else.

Permissions

A key carries exactly the permissions it was granted at creation. Nothing is added later: a key created before a feature existed does not silently gain access to it, and a key deliberately scoped without a permission keeps that scoping.

Calling an endpoint the key lacks permission for returns 403 with error.code of FORBIDDEN. That is different from 401, which means the key was missing or unusable. If you get a 403 from a request you expect to work, check the key's permissions in Settings → API Keys rather than the key itself.

Keeping keys safe

• Send keys only from server-side code. Anything in a browser is public.
• Give each integration its own key, so one can be revoked without disturbing the others.
• Use a sk_test_ key everywhere that is not production. See Test and live data.