API Auth

Authenticate API requests and understand keys, scopes, permissions, rate limits, idempotency, and rotation.

Use https://app.gtmclarity.ai/api/v1 as the API base URL. The dedicated host https://api.gtmclarity.ai/v1 is coming.

Send the bearer token

API keys start with gtmc_, followed by 32 random bytes encoded as base64url. GTM Clarity stores each key as a SHA-256 hash and keeps a 12-character display prefix for identification.

Send the key in the Authorization header:

curl https://app.gtmclarity.ai/api/v1/customers \
  -H 'Authorization: Bearer gtmc_your_key_here'

Choose a tier and scope

Access has two axes: tier controls allowed verbs, and scope controls which customers the key can access.

Axis	Value	Meaning
Tier	`read`	Read endpoints only.
Tier	`write`	Includes `read`, plus write endpoints.
Tier	`admin`	Includes `read` and `write`, plus administrative endpoints.
Scope	`agency`	Every customer in your org.
Scope	`customer`	One bound `customerId`.
Scope	`platform_admin`	Internal-only. Cannot be minted via the API.

Endpoint permissions

Endpoint group	Method	Required tier
`customers`	`GET` / list	`read`
`customers`	`POST`	`write`
`customers`	`PATCH`	`write`
`customers`	`DELETE`	`admin`
`conversations`	`GET`	`read`
`messages`	`GET`	`read`
`identities`	`GET`	`read`
`widget-config`	`GET`	`read`
`widget-config`	`PATCH`	`write`
`webhook-endpoints`	`GET`	`read`
`webhook-endpoints`	`POST`	`write`
`webhook-endpoints`	`PATCH`	`write`
`webhook-endpoints`	`DELETE`	`admin`
`webhook-endpoints/rotate-secret`	`POST`	`write`
`webhook-endpoints/deliveries`	`GET`	`read`
`conversions`	`GET`	`read`
`resolutions`	`GET`	`read`
`usage`	`GET`	`read`, org-level agency keys only
`usage/timeseries`	`GET`	`read`, org-level agency keys only
`keys`	`GET`	`admin`
`keys`	`POST`	`admin`
`keys/[id]`	`DELETE`	`admin`
`keys/[id]/rotate`	`POST`	`admin`

Handle errors

Errors use this envelope:

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Missing, malformed, invalid, or expired API key",
    "request_id": "<uuid>"
  }
}

The type value is one of:

invalid_request_error
authentication_error
permission_error
rate_limit_error
idempotency_error
not_found_error
api_error

Every response carries X-Request-Id. 401 responses also carry WWW-Authenticate: Bearer.

Respect rate limits

Rate limits use a per-minute fixed window per key:

Tier	Limit
`read`	600/min
`write`	120/min
`admin`	60/min

Every response includes:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset, as Unix seconds

429 responses also include Retry-After, in seconds.

Use idempotency for customer creation

Send Idempotency-Key on POST /api/v1/customers when creating customers from a retrying job or CI flow:

curl https://app.gtmclarity.ai/api/v1/customers \
  -X POST \
  -H 'Authorization: Bearer gtmc_your_key_here' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: customer-create-acme-2026-07-19' \
  -d '{
    "name": "Acme"
  }'

The replay window is 24 hours. A replay of the same key and same body carries Idempotent-Replay: true. Reusing the same key with a different body returns 409 with idempotency_error and key_reused.

Secret-returning POSTs deliberately do not support idempotency, because a replay would re-leak a secret. This includes keys, key rotation, webhook endpoint creation, and webhook secret rotation.

Rotate a key

Rotate key material with an admin key:

curl https://app.gtmclarity.ai/api/v1/keys/12/rotate \
  -X POST \
  -H 'Authorization: Bearer gtmc_admin_key_here'

Rotation keeps the same key row, immediately kills the old plaintext key, and returns the new plaintext key once.