API key reference

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.

The program API key at a glanceCopy Anchor Link

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

Where to find itCopy Anchor Link

1. Select Settings in the left menu of your program.
2. Under Developer, select API Key.

A program is given a key the moment it is created, but creating a program does not hand that value back to you. To get a key you can put in an environment variable, a workspace owner selects Generate — or Regenerate, if one was generated before — on the API Key tab. The full value appears in the response to that action, 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 tab shows a masked value with only the last few characters visible. If you no longer have the current value stored anywhere, you cannot recover it: generate 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 is returned in exactly one place: the response to the owner's own regenerate request.

Which calls need itCopy Anchor Link

Every endpoint above is documented in the API reference.

Replace a keyCopy Anchor Link

Regenerate 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 a workspace owner can generate or regenerate a program key. A member who tries is refused, so ask an owner to run 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 Settings → API Key, regenerate the key. The old key stops working at that moment.
3. Copy the new value from the one-time reveal, update those places, and redeploy.

When Affitor asks you to replace a keyCopy Anchor Link

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.

Replacing the key clears the flag: regenerate it in Settings → API Key and the warnings stop.

Agent API keysCopy Anchor Link

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. See Agent Integration.

Which key do I send?Copy Anchor Link

Verify it workedCopy Anchor Link

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.