Authentication
Every request except GET /v1/ carries an API key as a bearer token:
Authorization: Bearer cg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxThe 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: 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:
\bcg_(live|test)_[A-Za-z0-9]{43}\bAdd 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_keyfrom the next request on. - The key shows as revoked in your key list, and your audit events (
GET /v1/audit-events) contain anapi_key.leakedevent 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.
Getting a key
You create keys yourself in the portal or over the API — see 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), - 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 names it per operation. A key without it gets 403 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 and the 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, or ask us. A request from anywhere else gets 403 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 with error.agreement_type. GET /v1/me shows the state; accept once in the portal or with POST /v1/agreements/{type}/accept and the current version from GET /v1/agreements.
These writes work before the terms are accepted:
| Operation | Endpoint |
|---|---|
acceptAgreement |
POST /v1/agreements/{type}/accept |
createApiKey |
POST /v1/api-keys |
rollApiKey |
POST /v1/api-keys/{id}/roll |
revokeApiKey |
DELETE /v1/api-keys/{id} |
inviteMember |
POST /v1/members |
deleteMember |
DELETE /v1/members/{id} |
extractFields |
POST /v1/extract |
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) are not checked against your account's terms.
API Terms
Using the API is governed by the API Terms of Use (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 and the current version from GET /v1/agreements (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 and in the changelog).
With a live key, these need the API Terms — otherwise 403 terms_not_accepted with error.agreement_type: "api_terms":
- creating or rolling a live key (
createApiKey,rollApiKey, in the portal as well), - registering a live OAuth app (
createOAuthApp), - every other write.
Always allowed, so a leaked secret can always be stopped: reads, revoking a key (revokeApiKey), deleting an OAuth app (deleteOAuthApp) or a webhook endpoint (deleteWebhookEndpoint), removing a member (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 (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, 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 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} — 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 with a grace period.
Authentication errors
| Status | code |
When |
|---|---|---|
401 |
missing_key |
No Authorization: Bearer header. |
401 |
invalid_key |
Unknown or revoked key. |
401 |
expired_key |
The key is past its expiry date. |
403 |
account_not_active |
Your account is pending approval or disabled. |
403 |
ip_not_allowed |
The caller's IP is not on the key's allowlist. |
403 |
insufficient_scope |
The key lacks the endpoint's scope. |
403 |
terms_not_accepted |
A write before your terms are accepted — or, with a live key, before the API Terms are. |
503 |
not_configured |
A setting is missing on our side, or test mode is briefly unavailable. |