API Keys

Almost every call to the TokenKit API needs an api-key header. The easiest way to get one is the dashboard at app.tokenkithq.io. If you'd rather mint keys from code, the endpoints below do it for you.

The headers you'll send on every other call

Once you have a key:

1curl 'https://api.tokenkithq.io/api/tokens/?common=true' \
2  -H 'api-key: YOUR_API_KEY'

For endpoints that mutate user-owned data (like creating new keys, deleting keys, or registering trackers), you also send a bearer token from a logged-in session:

1curl '...' \
2  -H 'api-key: YOUR_API_KEY' \
3  -H 'Authorization: Bearer YOUR_SESSION_TOKEN'

Log in

POST /api/users/auth/login/ exchanges username/email + password for a session token.

1curl -X POST 'https://api.tokenkithq.io/api/users/auth/login/' \
2  -H 'Content-Type: application/json' \
3  -d '{"username": "you@example.com", "password": "..."}'

The response gives you a token you can pass as Authorization: Bearer <token> on later calls.

Mint a new API key

POST /api/users/auth/create-api-key/. Authenticated with the bearer token from login.

When you create a key you tell TokenKit where it is allowed to be used. Two lists, both optional:

• allowed_origins - the domains the key can be sent from in a browser. Required if you plan to call the API from a webpage (the key is visible in the browser, so we have to lock it to your origin or anyone can copy it).
• allowed_ips - the source IPs the key can be sent from when there is no Origin header (server-side use, cron jobs, scripts).

If a list is empty, no restriction on that axis. You can leave both empty if you really want an "open" key, but we strongly recommend setting at least one.

1# A frontend key for one or more web origins
2curl -X POST 'https://api.tokenkithq.io/api/users/auth/create-api-key/' \
3  -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "name": "my-app-prod",
7    "allowed_origins": ["https://app.example.io", "https://www.example.io"],
8    "rate_limit_per_hour": 5000
9  }'

1# A server key for a backend job
2curl -X POST 'https://api.tokenkithq.io/api/users/auth/create-api-key/' \
3  -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "name": "indexer-cron",
7    "allowed_ips": ["203.0.113.10"],
8    "rate_limit_per_hour": 10000
9  }'

The full key is returned once. Save it. We only store a hash, so we cannot show it to you again.

How enforcement works

If a request fails the check, you get 403 Forbidden and the failure is logged against the source IP. Ten failures from one IP in 5 minutes blocks that IP from any further key attempts for the rest of the window.

List your keys

GET /api/users/auth/api-keys/. Authenticated.

1curl 'https://api.tokenkithq.io/api/users/auth/api-keys/' \
2  -H 'Authorization: Bearer YOUR_SESSION_TOKEN'

You get back a list of key metadata (id, name, created_at, last_used_at). The actual key values are never returned.

Delete a key

POST /api/users/auth/api-keys/delete/. Authenticated.

1curl -X POST 'https://api.tokenkithq.io/api/users/auth/api-keys/delete/' \
2  -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \
3  -H 'Content-Type: application/json' \
4  -d '{"key_id": 123}'

Once deleted, any request still using that key gets 401 Unauthorized.

See also

• Authorization - the headers TokenKit expects on every API call