Authentication - GainTrace

Every request must include an API key as a Bearer token:

curl https://app.gaintrace.com/api/v1/companies \
  -H "Authorization: Bearer gt_live_your_key_here"

Create and manage keys in Settings → API Keys. A key is shown once at creation — store it securely.

Key types

Secret keys — gt_live_

Full server-side keys. Use only from your backend, never in a browser. Gated by the workspace’s API-v1 entitlement.

Publishable keys — gt_pub_

Client-safe, write-only keys for browser ingest. Origin-pinned and CORS-enabled, with only the write:ingest scope. Safe to ship in front-end code.

Scopes

Each key is granted a set of scopes. A request needs the scope its endpoint requires, or it returns 403 Insufficient scope. A key with the * scope passes any check.

Endpoint	Method	Required scope
`/companies`, `/companies/{id}`	GET	`read:companies`
`/companies`, `/companies/{id}`	POST, PATCH	`write:companies`
`/contacts`, `/contacts/{id}`	GET	`read:contacts`
`/contacts`, `/contacts/{id}`	POST, PATCH, DELETE	`write:contacts`
`/signals`, `/signals/{id}`	GET	`read:signals`
`/signals`, `/signals/batch`, `/signals/{id}`	POST, PATCH, DELETE	`write:signals`
`/webhooks`, `/webhooks/{id}`	GET	`read:webhooks`
`/webhooks`, `/webhooks/{id}`, `/webhooks/{id}/test`	POST, PATCH, DELETE	`write:webhooks`
`/events`	POST	`write:events` or `write:ingest`
`/metric-events`	POST	`write:events`

Grant only what a key needs. Other scopes exist for surfaces not yet on the public API (for example read:revenue, read:health, read:deals).

Errors

Every error returns the same envelope: a machine-readable code, a safe message, and a doc_url.

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient scope: write:companies required",
    "doc_url": "https://docs.gaintrace.com/errors#forbidden"
  }
}

Status	Code	Meaning
`400`	`bad_request`	The request could not be parsed (for example, malformed JSON).
`401`	`unauthorized`	Missing `Authorization` header, or an expired, revoked, or invalid key.
`402`	`payment_required`	A plan limit was reached, or billing is locked.
`403`	`forbidden`	The key lacks the required scope, the origin is not allowed, or API v1 is not enabled.
`404`	`not_found`	The resource, or a resource you referenced, is not in this workspace.
`409`	`conflict`	The request clashes with an existing resource (for example, a duplicate email).
`422`	`unprocessable_entity`	The request was well-formed but a value failed validation.
`429`	`rate_limit_exceeded`	The key’s rate limit was exceeded. Back off and retry.
`500`	`internal_server_error`	Something went wrong on our side. Retry shortly.
`503`	`service_unavailable`	A backing service was briefly unavailable. Retry shortly.
`504`	`gateway_timeout`	The request took too long upstream. Retry, and use smaller batches.

Branch on error.code, not the message. The full reference, including what to do for each, is on the Errors page.

Treat gt_live_ keys like passwords. If one leaks, revoke it in Settings > API Keys. Validation checks revocation on every request.

​Key types

Secret keys — gt_live_

Publishable keys — gt_pub_

​Scopes

​Errors

Key types

Scopes

Errors