API Keys & Tokens

Get the program tracking token and Management API keys you need to track conversions and configure programs programmatically.

Affitor uses two different credentials. Knowing which one to use is the step between "program created" and "conversions tracked".

Who this is for

Advertisers wiring up tracking or automating program setup

Time required

5 minutes

Prerequisites

An advertiser account and at least one program

Outcome

You know which key to send, where to get it, and how to rotate it safely

Two credentials, two jobs

Program tracking token

Prefix aff_. Authenticates server-side tracking calls (clicks, leads, sales, refunds) for a single program. This is the "program API key" referenced throughout the tracking guides.

Management API key

Prefix affk_. Authenticates the Management API so you can create, update, and publish programs programmatically — without a browser session.

Info

The prefixes are deliberately distinct (aff_ vs affk_) so Affitor can tell the two key types apart from the Authorization header alone. Sending the wrong one returns 401.

Program tracking token (`aff_`)

Every program gets a tracking token automatically when it is created. You send it as a Bearer token on tracking requests:

curl -X POST https://api.affitor.com/api/v1/track/sale \
  -H "Authorization: Bearer aff_your_program_token" \
  -H "Content-Type: application/json" \
  -d '{ "transaction_id": "txn_abc123", "customer_key": "user_123", "amount_cents": 9999 }'

Where to find it

Dashboard — open your program's settings; the token is shown masked (for example aff_abcdefgh****wxyz).
API responses — program read endpoints never return the raw token. They expose api_token_masked only, so a leaked read response can't be used to forge tracking calls.

The full token is shown once, at the moment it is generated or regenerated. Store it in a secret manager or your backend environment (for example AFFITOR_API_KEY) — not in client-side code.

Rotate a compromised token

Regenerating immediately invalidates the previous token and returns a new one exactly once:

curl -X POST \
  https://api.affitor.com/api/advertiser/affiliate-programs/:id/regenerate-api-token \
  -H "Authorization: Bearer affk_your_management_key"

{
  "data": {
    "api_token": "aff_the_new_full_token_shown_once",
    "api_token_masked": "aff_abcdefgh****wxyz"
  }
}

Regenerating breaks any integration still using the old token. Update your backend environment before rotating in production.

At rest

Tokens are stored as a SHA-256 hash and matched by hash on every tracking request, so the raw value is never persisted in a readable form after issuance.

Management API key (`affk_`)

Management API keys let scripts and internal tools drive Affitor without a logged-in browser session. Use them to automate program creation, updates, and go-live.

Create a key

Call the endpoint while authenticated with your dashboard session. The full key is returned once — copy it immediately.

curl -X POST https://api.affitor.com/api/advertiser/api-keys \
  -H "Authorization: Bearer <your_session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI deploy bot",
    "scopes": ["program:read", "program:update"],
    "program_scope": null,
    "expires_at": null
  }'

{
  "data": {
    "id": 7,
    "name": "CI deploy bot",
    "prefix": "affk_1a2b3c4d",
    "scopes": ["program:read", "program:update"],
    "program_scope": null,
    "status": "active",
    "key": "affk_the_full_key_shown_once",
    "key_masked": "affk_1a2b3c…c4d5"
  }
}

namestringRequired

Human-readable label so you can recognise the key later.

scopesstring[]Optional

Allowed actions. Defaults to ["*"] (all actions). See the scope table below.

program_scopestring[] | nullOptional

Limit the key to specific program IDs. null (default) means every program the advertiser can access.

expires_atdatetime | nullOptional

Optional expiry. After this time the key is rejected. null means no expiry.

Available scopes

Scope	Grants
`*`	Every action below
`program:list`	List your programs
`program:read`	Read a single program
`program:create`	Create a program
`program:update`	Update program settings (including slug)
`program:delete`	Delete a program
`program:go_live`	Publish a program to the marketplace
`program:regenerate-token`	Rotate a program's tracking token
`dashboard:view`	Read dashboard summary and program aggregates

Use a key

Send it as a Bearer token on any /api/advertiser/* Management endpoint:

curl https://api.affitor.com/api/advertiser/affiliate-programs \
  -H "Authorization: Bearer affk_your_management_key"

Info

Management endpoints accept either a dashboard session or an affk_ key. Scripts should use an affk_ key; the browser dashboard uses your session automatically.

Manage keys

Action	Endpoint
List (masked)	`GET /api/advertiser/api-keys`
Update name / scopes / program scope	`PUT /api/advertiser/api-keys/:id`
Revoke	`DELETE /api/advertiser/api-keys/:id`

Revoking is a soft action — it sets the key's status to revoked and rejects it from then on, while keeping the record for your audit trail. Keys are stored hashed; listing only ever returns the masked prefix, never the secret.

Which key do I send?

Your task	Key to send
Track a conversion — clicks, leads, sales, refunds	Program tracking token (`aff_`)
Configure programs from code — create, update, publish in a script or CI	Management API key (`affk_`)

Next recommended step

Track your first conversion

With your program tracking token in hand, wire up clicks, signups, and sales end to end.

Open tracking quickstart →

On this page