Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

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: 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.

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":

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.