Dokumentacja
Management API
A management key lets your own systems create, group, limit and revoke the API keys of your account, and read what they spent, over the API. It cannot call a model.
What it is for
Some integrations give each of their customers, teams or users an API key of their own, put the keys of each customer into a group, cap what a group may spend and read the cost back by key or by group. On the API Keys page that is fine for a few keys. For more, a management key lets a script or your own admin tool do the same through the API.
A management key is a different credential from an API key. It is not accepted where an API key is: it cannot call /v1/chat/completions, /v1/messages or any other model route. It works only on /v1/management/, and an API key does not work there.
Create a management key
- Open the API Keys page and go to the foot of it. Under Management keys, choose New management key. The block stays folded until you open it.
- Give the key a name, for example billing sync, so the page can say which program made each change.
- Enter the addresses it may be called from, one to a line: a single address such as 203.0.113.7, or a range such as 203.0.113.0/24. Without an allowlist, anyone who holds the key can use it, and the dialog warns you if you leave the list empty.
- Copy the key when it is shown. It is shown once: Kunavo keeps only a hash of it.
An account can hold two active management keys at once. Revoke one to make room for another.
Call it
Send the key as a bearer token to https://api.kunavo.com/v1/management. Management keys are not accepted from a browser: their answers carry no CORS headers, so a page on another site cannot call them. A key belongs on your server, never in front-end code.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Answers are JSON. Errors have the same shape as the rest of the API: an error object with a message, a type, a code and, where it applies, the param that is wrong. These are the statuses you will meet:
| Status | What it means |
|---|---|
401 | The key is missing, mistyped or revoked, or its account is suspended or under review. |
403 | The key has an IP allowlist and the request came from an address that is not on it. |
404 | The group or key does not exist, is deleted, or belongs to another account. All three answer alike, so an id from another account reveals nothing. |
409 | The change conflicts with the account's state: a group name already in use, a revoked key, or the account at its ceiling of 500 active keys. |
429 | This key has made 60 requests in the last minute. The Retry-After header says how many seconds to wait. |
Groups
GET /v1/management/groups lists the account’s groups, with each one’s monthly limit and how many active keys it holds. POST creates one, with an optional monthly_limit_usd; a name already in use is a 409. PATCH /v1/management/groups/{id} changes the name or the limit: send null for no limit, and 0 to pause every key in the group without revoking any. DELETE removes a group, and its calls keep its name on the Usage page. Its keys stay active and become ungrouped, unless you add ?revoke_keys=true, which revokes them too.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001", "monthly_limit_usd": 50}'Keys
GET /v1/management/keys lists keys, newest first. A page holds 50 keys, and limit raises that to 100. status is active by default, or revoked or all, and group_id narrows the list to one group. When has_more is true, pass next_after as after to read the next page. A key’s plaintext is never listed.
POST /v1/management/keys creates a key with a name and, optionally, a group_id, a monthly_limit_usd and an ip_allowlist. The answer carries the plaintext in its key field, once. A POST that is repeated makes a second key, so before you retry one, list the keys and look for its name.
curl https://api.kunavo.com/v1/management/keys \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'PATCH /v1/management/keys/{id} changes a key’s name, group, limit or allowlist; a group_id of null takes it out of its group. DELETE revokes it. Revoking a key that is already revoked is not an error. A revoked key cannot be changed.
curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Usage
GET /v1/management/usage reports the usage of the whole account over up to 90 UTC days, as GET /v1/usage reports one key’s. group_by takes any mix of group, api_key, model and day, and defaults to api_key. The figures mean what they mean on the Usage page: a call counts in the group its key was in when it was made, a failed call costs nothing, and the total for a period equals the CSV export of the same days to the cent. group_id and api_key_id narrow the report to one group or one key.
curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"end_date after today is read as today, and the answer echoes the end date it used.Keep it safe
- Set an allowlist. A key that only works from your server’s addresses is worth little to someone who steals it.
- Keep the key in a secret store on the server that runs your tool. Never put it in a browser, a mobile app or a repository.
- If it leaks, revoke it at the foot of the API Keys page, or with
DELETEon it. The revoke dialog can also revoke the keys that key created. - Every change the key makes through the API is listed under Management keys on the API Keys page, with its time, the address it came from and the key that made it: the last 50 changes. Changes made by hand on that page are not listed.
- A key stops working by itself when its account is suspended or put under review, and when it is revoked.
A management key may make 60 requests a minute. Make one request for each change, and read a list in pages rather than one key at a time.
Related
Groups, their monthly limits and the way their figures are counted are explained on the key groups page. The usage figures are the same as on the usage page.