# Authentication

Every request except `GET /v1/` carries an API key as a bearer token:

```http
Authorization: Bearer cg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The key identifies your account. Everything you create is attributed to it, so there is no account id in requests.

## Key format

A key is `cg_live_` (live mode) or `cg_test_` ([test mode](https://docs.creator-guard.com/test-mode/): same URLs, sandbox data) followed by 43 letters and digits, 51 characters in total. The 43 characters are generated randomly (about 256 bits). The first 12 characters (for example `cg_live_ab12`) are the key's **prefix**: it is stored in clear so you and our team can tell keys apart, and the portal shows it under **Settings → API**.

The prefix is distinctive on purpose, so that secret scanners recognise a key that ended up somewhere public. The exact pattern:

```text
\bcg_(live|test)_[A-Za-z0-9]{43}\b
```

Add it to your own secret scanning (pre-commit hooks, CI) so a key never reaches a repository in the first place.

### Leaked keys

A key that was public must be treated as compromised. When a Creator Guard key is reported to us as public — by you, by anyone else, or by an automated secret scanner such as GitHub's — we revoke it immediately, without asking first. A revoked key cannot be re-enabled.

- Requests with the key fail with `401 invalid_key` from the next request on.
- The key shows as revoked in your key list, and your audit events (`GET /v1/audit-events`) contain an `api_key.leaked` event with the public URL where it was found, if known.
- We email your account's contact address with the key's prefix and label.

Create a new key (or ask us for one), switch your system over, and remove the old key from the repository's history.

OAuth client secrets (`cgcs_`) and the access and refresh tokens your app holds for creators (`cgo_`, `cgr_`) are watched the same way; what happens then is described under [OAuth](https://docs.creator-guard.com/oauth/).

## Getting a key

You create keys yourself in the portal or over the API — see [API keys](https://docs.creator-guard.com/api-keys/); our team can issue them too. Each key has:

- a **label** (for example "CRM production"),
- **scopes** — what it may do (below),
- optionally an **expiry date** (after it: [`401 expired_key`](https://docs.creator-guard.com/errors/#expired_key)),
- optionally an **IP allowlist** (below).

The full key is shown **once**: in the portal right after you create it, or in `secret` of the API answer. Keys our team issues are handed over through a channel we agree with you (never plain email or chat). Copy it straight into your secret store. Only a SHA-256 hash is kept; if you lose the key, roll it or create a new one and revoke the old one.

## Scopes

Each endpoint needs one scope; the [reference](https://docs.creator-guard.com/reference/) names it per operation. A key without it gets [`403 insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope) with `error.scope`.

| Scope | Allows |
|---|---|
| `account:read` | `GET /v1/me`, agreements and their texts, option lists, settings |
| `agreements:write` | Accepting agreements |
| `leads:read` | Reading leads, listings, confirmations and timelines |
| `leads:write` | Creating and changing leads and listings, consent links, submitting for review, withdrawing |
| `earnings:read` | `GET /v1/leads/{id}/earnings` |

These are the five scopes the portal preselects; all nineteen scopes and what each allows: [API keys](https://docs.creator-guard.com/api-keys/#scopes) and the [Scope](https://docs.creator-guard.com/reference/#schema-Scope) list in the reference.

## IP allowlist

A key can be limited to IP addresses or ranges (CIDR, IPv4 and IPv6) — set `ip_allowlist` when you [create the key over the API](https://docs.creator-guard.com/api-keys/#with-the-api), or ask us. A request from anywhere else gets [`403 ip_not_allowed`](https://docs.creator-guard.com/errors/#ip_not_allowed) and does not count against the key's rate limits.

## Terms

Reads work with any active account. **Writes** need your account's terms accepted (any version): referrer accounts `referrer_terms`, agency accounts `agency_terms`. Without them a write gets [`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) with `error.agreement_type`. `GET /v1/me` shows the state; accept once in the portal or with [`POST /v1/agreements/{type}/accept`](https://docs.creator-guard.com/reference/#op-acceptAgreement) and the current `version` from [`GET /v1/agreements`](https://docs.creator-guard.com/reference/#op-listAgreements).

These writes work before the terms are accepted:

| Operation | Endpoint |
|---|---|
| [`acceptAgreement`](https://docs.creator-guard.com/reference/#op-acceptAgreement) | `POST /v1/agreements/{type}/accept` |
| [`createApiKey`](https://docs.creator-guard.com/reference/#op-createApiKey) | `POST /v1/api-keys` |
| [`rollApiKey`](https://docs.creator-guard.com/reference/#op-rollApiKey) | `POST /v1/api-keys/{id}/roll` |
| [`revokeApiKey`](https://docs.creator-guard.com/reference/#op-revokeApiKey) | `DELETE /v1/api-keys/{id}` |
| [`inviteMember`](https://docs.creator-guard.com/reference/#op-inviteMember) | `POST /v1/members` |
| [`deleteMember`](https://docs.creator-guard.com/reference/#op-deleteMember) | `DELETE /v1/members/{id}` |
| [`extractFields`](https://docs.creator-guard.com/reference/#op-extractFields) | `POST /v1/extract` |
| [`testReset`](https://docs.creator-guard.com/reference/#op-testReset) | `POST /v1/test-helpers/reset` (test keys only) |

The terms check applies to account API keys only. Requests with a creator's OAuth access token ([creator API](https://docs.creator-guard.com/creator-api/)) are not checked against your account's terms.

## API Terms

Using the API is governed by the [API Terms of Use](https://docs.creator-guard.com/legal/api-terms/) (`api_terms`), in addition to your account's terms. Your account accepts them **once**, by an **owner or admin**: in the portal under **Settings → API**, or with [`POST /v1/agreements/api_terms/accept`](https://docs.creator-guard.com/reference/#op-acceptAgreement) and the current `version` from [`GET /v1/agreements`](https://docs.creator-guard.com/reference/#op-listAgreements) (only keys of an owner or admin carry `agreements:write`; a developer or viewer asks one of them). The acceptance counts for live and test keys alike. Any accepted version counts, unless we publish a version marked as needing re-acceptance (announced with [`agreement.published`](https://docs.creator-guard.com/events/) and in the [changelog](https://docs.creator-guard.com/changelog/)).

With a **live key**, these need the API Terms — otherwise [`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) with `error.agreement_type: "api_terms"`:

- creating or rolling a live key ([`createApiKey`](https://docs.creator-guard.com/reference/#op-createApiKey), [`rollApiKey`](https://docs.creator-guard.com/reference/#op-rollApiKey), in the portal as well),
- registering a live OAuth app ([`createOAuthApp`](https://docs.creator-guard.com/reference/#op-createOAuthApp)),
- every other write.

Always allowed, so a leaked secret can always be stopped: reads, revoking a key ([`revokeApiKey`](https://docs.creator-guard.com/reference/#op-revokeApiKey)), deleting an OAuth app ([`deleteOAuthApp`](https://docs.creator-guard.com/reference/#op-deleteOAuthApp)) or a webhook endpoint ([`deleteWebhookEndpoint`](https://docs.creator-guard.com/reference/#op-deleteWebhookEndpoint)), removing a member ([`deleteMember`](https://docs.creator-guard.com/reference/#op-deleteMember)) and accepting terms. **Test keys** and the sandbox never need the API Terms, and requests with a creator's OAuth access token are never checked against them.

**Transition.** An account that already held a live key when the API Terms were published keeps working for **30 days**; the date is in the portal (Settings → API). After it, the rules above apply. An account without a live key at that time accepts them before its first live key.

## Data protection addendum

The [data protection addendum](https://docs.creator-guard.com/legal/dpa/) (`api_dpa`) covers the personal data you and we exchange through the API, including the EU Standard Contractual Clauses for transfers to the USA. It works like the API Terms: your account accepts it **once**, by an **owner or admin**, in the portal under **Settings → API** or with [`POST /v1/agreements/api_dpa/accept`](https://docs.creator-guard.com/reference/#op-acceptAgreement), and the acceptance counts for live and test keys.

It is needed for the same live actions as the API Terms, with the same exceptions; without it they answer [`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) with `error.agreement_type: "api_dpa"` (when both are missing, `api_terms` is named first). An account that already held a live key when the addendum was published keeps working for **30 days** (the date is in the portal); an account without a live key accepts it before its first one.

## Keep it secret

- **Server-side only.** Never in a browser, a mobile or desktop app you ship, or a public repository. The API sends no CORS headers.
- Load it from an environment variable or a secret manager.
- Send it only to `https://api.creator-guard.com`.

## Revoking a key

If a key may have leaked, revoke it in the portal or with [`DELETE /v1/api-keys/{id}`](https://docs.creator-guard.com/api-keys/#revoking) — or tell us and we revoke it at once. Revocation applies to the **very next request** (no cache). To rotate without downtime, [roll the key](https://docs.creator-guard.com/api-keys/#rolling-without-downtime) with a grace period.

## Authentication errors

| Status | `code` | When |
|---|---|---|
| `401` | [`missing_key`](https://docs.creator-guard.com/errors/#missing_key) | No `Authorization: Bearer` header. |
| `401` | [`invalid_key`](https://docs.creator-guard.com/errors/#invalid_key) | Unknown or revoked key. |
| `401` | [`expired_key`](https://docs.creator-guard.com/errors/#expired_key) | The key is past its expiry date. |
| `403` | [`account_not_active`](https://docs.creator-guard.com/errors/#account_not_active) | Your account is pending approval or disabled. |
| `403` | [`ip_not_allowed`](https://docs.creator-guard.com/errors/#ip_not_allowed) | The caller's IP is not on the key's allowlist. |
| `403` | [`insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope) | The key lacks the endpoint's scope. |
| `403` | [`terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) | A write before your terms are accepted — or, with a live key, before the [API Terms](#api-terms) are. |
| `503` | [`not_configured`](https://docs.creator-guard.com/errors/#not_configured) | A setting is missing on our side, or test mode is briefly unavailable. |
