Settings and keys

API key reference

Which credential each Affitor call needs, where the program API key lives, how to replace it, and how mandatory rotation is signalled.

View as Markdown

Affitor has one self-serve credential: the program API key. It authenticates server-side tracking calls for a single program, you manage it yourself from the dashboard, and it is the key the integration guides, the SDKs, the CLI's tracking setup, and the agent skill all refer to. CLI commands that create or list programs are different: they act as your account, so they authenticate with your CLI login rather than with this key.

Who this is for
Brands wiring up server-side tracking, and the agents doing it for them
Time required
5 minutes
Prerequisites
A brand account with at least one program. Creating or rotating a key also needs owner or admin access to that program.
Outcome
You know which key to send, where to get it, how to replace it, and what a rotation warning means

The program API key at a glance

PropertyValue
Prefixaff_
ScopeOne program. A key authenticates calls for the program it belongs to and nothing else.
PermissionFull access sends tracking events and reads your stats. Tracking only sends clicks, signups, sales, refunds and chargebacks; the readiness check, analytics and the CLI's status and test answer 403 insufficient_key_permission to it. The CLI and the agent skill need Full access. You choose it in Create key or Edit key.
Sent asAuthorization: Bearer <key>
CreatedAutomatically, when the program is created. Owners and admins can create more keys and rotate any key at any time.
VisibilityNever returned by a read. In the dashboard the full value is shown once, in Copy your key, right after Create key or Rotate key, so copy it there.
# Test mode: checks that the key authenticates, without creating a real sale or commission.
curl -X POST https://api.affitor.com/api/v1/track/sale \
  -H "Authorization: Bearer $AFFITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "additional_data": { "test_mode": true } }'

A 200 with test_mode: true in data means the key works. The call is not a no-op: it stores a sale event flagged as a test, writes a tracking log entry, and can move your integration checklist. It creates no commission and no platform fee. A real sale needs a transaction_id and a customer that already carries attribution — see Track a sale.

Info

Keys issued before the short prefix was introduced do not start with aff_. Authentication is an exact match on the key itself, so those keys keep working; rotating gives you an aff_ key.


Where to find it

  1. In the program menu (your program's name at the top of the left menu), choose Program settings.
  2. Under Developers, select API keys.

A program is given a key the moment it is created, but creating a program in the dashboard does not show you that value (affitor init writes the key of the program it creates to .affitor/.env). To get a key you can put in an environment variable, an owner or admin selects Create key on the API keys page, or Rotate key in the ⋯ menu on an existing key's row. The full value appears in Copy your key, and only there. Copy it then and store it server-side:

# .env — server-side only. Never ship this key to the browser.
AFFITOR_API_KEY=YOUR_PROGRAM_API_KEY

After that the Key column shows only a short hint of the key. If you no longer have the current value stored anywhere, you cannot recover it: rotate the key or create a new one instead. The full click-path, including the one-time reveal, is in Manage program settings and your API key.

Program read endpoints never return the key. They expose api_token_masked only, so a leaked read response cannot be used to forge tracking calls. The value itself comes back only in a response that issues a new key, such as Create key, Rotate key, or affitor init creating a program.


Which calls need it

CallKey required
POST /api/v1/track/saleYes
POST /api/v1/track/refundYes
POST /api/v1/track/lead — server modeYes. Sending the key is what makes the signup a server-attributed lead.
POST /api/v1/track/lead — browser modeNo. The click cookie carries the attribution. On a program that requires server-side lead tracking, a browser lead is stored as provisional — the response says provisional: true — and a server-mode call is what settles it.
POST /api/v1/track/clickNo. Click tracking is public.

Every endpoint above is documented in the API reference.


Replace a key

Rotate the key if it may have leaked, if it was committed to a repository, or as routine hygiene when someone with key access leaves.

Only an owner or admin of the program can create or rotate a key. Other members do not see the keys table, so ask an owner or admin to rotate it and to hand you the new value through your secret manager.

  1. Line up every place AFFITOR_API_KEY is stored — deployment environment, secret manager, CI — so you can update them the moment you have the new value.
  2. In Program settings › Developers › API keys, open the ⋯ menu on the key's row, select Rotate key, then confirm with Rotate key. The old key stops working at that moment.
  3. Select Copy in Copy your key, update those places, and redeploy.
Warning

The two keys never overlap. Rotate key stops the old key at once, and you receive the new value only in Copy your key, so there is no way to deploy it in advance. Between the rotation and the redeploy, calls still sending the old key get 401. Pick a window where a short gap in server-side tracking is acceptable.


When Affitor asks you to replace a key

Affitor can mark a specific program key for mandatory rotation — for example after the key was exposed outside your control. Marking it sets a deadline, and the two sides of that deadline behave differently:

  • Before the deadline, the key still authenticates requests, so tracking keeps running until you are ready to swap it. Every response to a call made with that key carries Deprecation and Sunset headers plus a Link header pointing at the error reference, and the JSON body gains a warnings array carrying the code api_key_rotation_required and the deadline.
  • At or after the deadline, the key stops working. Requests come back as 401 with the same code in error.code, and the three headers are still there. That response has no warnings array — the warning only exists while the key still works.

Replace the key before the deadline: past it, the old key is refused whether or not you are ready. Doing it early does not remove the changeover gap described under Replace a key — it only lets you choose when that gap happens. Branch on the code, not on the message text. The full header and body shapes are in api_key_rotation_required.

Rotating the key clears the flag: select Rotate key on its row in Program settings › Developers › API keys, deploy the new value, and the warnings stop.


Agent API keys

Separately from program keys, Affitor issues agent API keys (prefix agt_) to approved tools that read and update programs on a brand's behalf through the /api/agent/v1/... endpoints.

These are issued by Affitor — there is no endpoint to create one yourself, and a program API key does not authenticate agent endpoints. Each agent endpoint also requires a specific scope on the key, so a valid agent key is still refused where it was not granted that scope. If you are building an integration that needs one, contact support.

If you only want an AI coding agent to install tracking for you, you do not need an agent key: point it at skill.md with your program API key in the environment. From a terminal, npx affitor onboard uses the same key to wire in the tracking it can and verify it: see affitor onboard.


Which key do I send?

Your taskKey to send
Report a sale, a refund, or a server-mode leadProgram API key (aff_), from Program settings › Developers › API keys
Record a click, or a browser-mode leadNo key — both are public calls. See Which calls need it.
Read or update programs on a brand's behalf via /api/agent/v1/...Agent API key (agt_), issued by Affitor

Verify it worked

Send a test-mode call with the key in hand: it goes through the same authentication as a real sale, then stops before any commission or platform fee is created. Every cause of a 401, and its fix, is listed in the error reference.

Verify success
Network
  • POST /api/v1/track/sale with additional_data.test_mode set to true returns 200 and test_mode: true in data — the key authenticates. The event is stored flagged as a test, and no commission or platform fee is created
  • After rotating, the same test-mode request with the old key returns 401: rotation is complete
  • Read the status before the body: a 200 with no warnings array means this key is not flagged for mandatory rotation. A flagged key that is past its deadline returns 401 and carries no warnings array either, so warnings alone never proves a key is unflagged
Dashboard
  • The API keys page (program menu → Program settings, then Developers → API keys) shows each key's short hint in the Key column, such as aff_…8d1e. When the hint shows the last four characters, they match the key your server sends
If it doesn't work
  • On a 401, read error.code first. api_key_rotation_required means the key passed its rotation deadline: rotate it, because copying the same key again will not bring it back. Other 401 responses can also mean the key is disabled: ask an owner or admin to check its status and select Enable key if it should be active. Otherwise, the header is malformed or the key matches no program: check the Authorization: Bearer prefix and your environment variable for trailing whitespace
  • A rejected call to /api/agent/v1/... has more than one cause, so read the error message instead of inferring from the status. Check the key type — only an agt_ key authenticates agent endpoints, a program key never does — and check that the agent key was granted the scope that endpoint requires
Next recommended step
Track your first conversion

With your program API key in hand, wire up clicks, signups, and sales end to end.

Open tracking quickstart →

On this page

Share feedback

Tell us what is missing or unclear on “API key reference”.