API keys
Create, inspect, verify and revoke the keys that authenticate every request.
API keys authenticate every request to the platform. Each key carries a set of scopes
(read, train, infer, admin) and can be bound to a
project, in which case it only sees that project's resources.
Production keys start with nk_live_, sandbox keys with nk_test_. See
Authentication for how to send the key.
The secret is returned exactly once, in the response that creates the key. It is never retrievable again: listing keys returns only the prefix, so store the secret in your secrets manager the moment you receive it.
To rotate a key, create the replacement, cut your deployment's traffic over to it, then revoke the old key. Both keys stay valid in between, so the rotation needs no downtime window.
List API keys
/v1/api-keysscope: adminReturns your organisation's API keys. The response never includes the secret, only the
prefix, which is enough to match a key against the value a deployment holds. last_used_at
tells you which keys are actually in use, so stale ones can be revoked with confidence.
curl https://api.nucleus-ai.io/v1/api-keys \
-H "Authorization: Bearer $NUCLEUS_API_KEY"{
"data": [
{
"id": "key_2Fd",
"name": "production-backend",
"prefix": "nk_live_8x",
"last_used_at": "2026-07-26T22:10:00Z"
}
]
}Create an API key
/v1/api-keysscope: adminCreates a key. Grant only the scopes the workload needs: a serving backend needs infer, a
training pipeline needs train, and neither needs admin. Binding the key to a project
with project_id stops one team's key reading another team's runs.
Body parameters
namestringrequiredHuman-readable name, e.g. the deployment that will hold the key.
scopesarrayScopes the key is granted, e.g. ["train", "infer"].
project_idstringBind the key to a project. The key can then only see that project's resources.
The secret field in the response is shown once and never retrievable. Store it
immediately, and only ever send it in the Authorization header, never in a query string,
where it would end up in access logs.
curl https://api.nucleus-ai.io/v1/api-keys \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "production-backend",
"scopes": ["train", "infer"],
"project_id": "proj_acme"
}'{
"id": "key_2Fd",
"secret": "nk_live_••••••••",
"note": "shown once, never retrievable"
}Revoke an API key
/v1/api-keys/{key_id}scope: adminRevokes a key immediately. Requests presenting it fail from that moment, so this is the incident-response path for a leaked key: revoke first, then issue a replacement.
For a planned rotation the order is reversed. Create the replacement, move traffic over,
then revoke the old key once List API keys shows its last_used_at has
gone quiet.
Path parameters
key_idstringrequiredID of the key to revoke.
curl -X DELETE https://api.nucleus-ai.io/v1/api-keys/key_2Fd \
-H "Authorization: Bearer $NUCLEUS_API_KEY"(empty body)Verify the current key
/v1/auth/verifyReturns what the key presented in the Authorization header is: its ID, name, prefix,
scopes, bound project and expiry. Any valid key can call it, regardless of scope, and the
call has no side effects.
This is the first call to make when a deployment starts returning 403. It tells you which key the deployment is actually presenting and what that key is allowed to do, which separates a wrong-key problem from a missing-scope problem in one request.
The endpoint takes no parameters; it reads the Authorization header.
curl https://api.nucleus-ai.io/v1/auth/verify \
-H "Authorization: Bearer $NUCLEUS_API_KEY"{
"key_id": "key_2Fd",
"name": "production-backend",
"prefix": "nk_live_8x",
"scopes": ["read", "infer"],
"project_id": "proj_acme",
"expires_at": null
}