Authentication

Every request to the Cooledge API is authenticated with an API key sent in the X-Api-Key request header. This is the authentication method for the public API today.

X-Api-Key: ck_live_AB12CD_your_secret_here

There is no session, no login exchange and no token refresh. Each request carries the key on its own. OAuth for partners and MCP is planned, not yet available, so for now the X-Api-Key header is how you authenticate.

Key format and lifecycle

A Cooledge API key looks like this:

ck_live_AB12CD_xxxxxxxxxxxxxxxxxxxxxxxx

It has two visible parts joined by underscores:

The identifier (prefix). The ck_live_AB12CD portion is the key identifier. It is stored and displayable, so you can recognise which key a request used without ever exposing the secret. When you have several keys, the prefix is how you tell them apart.
The secret. Everything after the prefix is the secret. You send the whole string, prefix and secret together, in the X-Api-Key header.

The full secret is shown once at creation and cannot be retrieved again. Store it in a secrets manager or an environment variable as soon as you receive it. If the secret is lost you cannot recover it, so you request a replacement key and rotate to it.

You create and manage API keys yourself from the Developers page in Settings, on the Growth and Scale plans. Each key carries the scopes you choose and can be rotated or revoked at any time. Treat the secret like a password: never commit it to source control, never put it in a client-side bundle and never share it in plain text.

Scopes

Each key is granted a set of scopes. A scope is a permission to read or write one kind of record. A request is allowed only if the key holds the scope the endpoint requires. Ask for the narrowest set of scopes that does the job.

Scope	What it allows
`customers:read`	Read customers and their sites
`customers:write`	Create, update and archive customers and sites
`jobs:read`	Read jobs and their details
`jobs:write`	Create, update and progress jobs
`quotes:read`	Read quotes and their line items
`quotes:write`	Create, update and send quotes
`invoices:read`	Read invoices and their payment state
`invoices:write`	Create, update and send invoices
`bookings:read`	Read bookings and scheduled visits
`bookings:write`	Create, reschedule and cancel bookings
`leads:read`	Read leads and their status
`leads:write`	Create, update and convert leads
`webhooks:manage`	Manage webhook subscriptions

The scopes your key actually holds are returned on the caller.scopes array from GET /v1/me, so you can confirm what a key can do at any time.

401 versus 403

The API distinguishes a credential that is wrong from a credential that is right but not permitted. The two cases need different fixes, so check the status code first.

A 401 means the credential is missing or invalid. The X-Api-Key header was absent, malformed or did not match a live key. Check that you are sending the header, that you copied the whole key including the secret and that the key has not been revoked. A 401 is about the credential itself, not about what it is allowed to do.

A 403 means the credential is valid but not permitted. The key was recognised, so authentication succeeded, but the request was refused. A 403 can mean any of these:

The key does not hold a scope the endpoint requires. Request a key with that scope or use a key that already has it.
The business is not on a plan tier that includes the endpoint.
The subscription has lapsed. An expired trial, a past due payment or a cancellation blocks all API access, reads and writes alike, until it is resolved. Once the subscription is active again, access returns.

So a 401 points you at the key. A 403 points you at the key's scopes or at the account's plan and subscription state. Errors follow the RFC 7807 problem-details format, covered in Pagination and errors.