Authentication

All v2 API requests require an API key. Keys are scoped to the organization of the user who created them.

Getting an API key

Generate a key in the app: Org settings → API keys → + New API key.

See API keys guide for step-by-step instructions.

Using the key

Include the key as a Bearer token on every request:

Authorization: Bearer tga_<your-key>

Example:

curl -H "Authorization: Bearer tga_abc123" \
  https://www.trackagoat.com/api/v2/projects

Key format

tga_<64 lowercase hex characters>

Example: tga_a1b2c3d4e5f6... (64 hex chars after the prefix).

Org scoping

Keys are org-scoped: all data returned is limited to the organization the key belongs to. A key can only read and write data inside its own org.

Scoping stops at the org boundary — it does not go down to the project level. A key grants access to every project in its org, including ones created after the key was issued. There is no way to issue a key that is limited to a single project.

Testing against the API

Because keys are org-wide, do not run integration tests with a key from an org that holds real data — a test POST or DELETE will hit production records.

Create a separate organization for testing and use a key from that org. It gives you complete isolation: separate creators, campaigns, conversions, and analytics, with no path back to your live org. Ask support to disable scraping on it, which also guarantees test conversions can never generate payout accruals.

This is how you get a sandbox on trackagoat — there is no separate sandbox host or test-mode key prefix. The base URL and key format are the same; the org is what separates test from live.

Permission scopes

Each key carries one or more permission scopes, chosen at creation time. The scope controls which HTTP methods the key may use:

New keys default to ['read', 'write'] unless you narrow the scopes at creation.

A write request made with a read-only key is rejected with 403 and meta.code = "insufficient_scope":

{
  "data": null,
  "error": "This action requires the 'write' scope. Granted: [read]",
  "meta": { "code": "insufficient_scope", "required": "write", "granted": ["read"] }
}

This applies to every mutating endpoint, including all payout writes (payout-methods, payout-structures, payout-payments, payout-accruals, their [id] sub-routes, and annotation writes).

Errors

{
  "data": null,
  "error": "Invalid or expired API key",
  "meta": { "code": "invalid_api_key" }
}