Skip to content

Scope, limit and manage your keys

Give each application a key with only the products it needs, an expiry, an IP allowlist and a monthly spend limit, and manage keys from code.

How it works

  1. 01

    Create a key in the dashboard, or with POST /api/v1/api-keys from a key that holds api_keys:write.

  2. 02

    Give it full access, or restrict it to the products and levels its application calls.

  3. 03

    Store the key when it is shown. It is never shown again.

Authentication

The endpoints that manage keys take a key like every other endpoint, but only one granted api_keys on purpose: read to list and get keys, write to create, change and revoke them. Full access never includes it.

Example

The answer to a create is the only place the key appears, as data.secret. Every other answer shows it as masked_key: nai_... and its last four characters. To make a key expire, add expires_at with a date in the future.

cURL
# Needs a key holding api_keys:write.
curl -X POST "https://my.neuronai.uz/api/v1/api-keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "name": "CI",
    "access": "restricted",
    "permissions": {"tts": "write"},
    "expires_at": "2030-01-01T00:00:00Z"
  }'

# The response's data.secret is shown only this once — store it now.

Full and restricted keys

A full key holds every product at its highest level, products added later included. It never includes api_keys, which is only ever granted on its own. Every key made before permissions existed is a full key.

A restricted key holds exactly the levels in its permissions and nothing else. A request it lacks the level for answers 403 insufficient_permissions, and the message names the permission, such as tts:write.

A level is none, read or write, and write includes read. Some products have no read, and the account has no write.

Permissions by product

The endpoints each level opens. Give a key only what its application calls.

ttsText to speech

Levelsnonereadwrite

tts:read
GET /api/v1/tts/jobs/{id}GET /api/v1/tts/jobs/{id}/audio
tts:write
POST /api/v1/tts/dialoguePOST /api/v1/tts/jobsPOST /api/v1/tts/synthesize
voicesVoices

Levelsnonereadwrite

voices:write
POST /api/v1/tts/voicesDELETE /api/v1/tts/voices/{id}PATCH /api/v1/tts/voices/{id}POST /api/v1/tts/voices/{id}/audio

Stock voices need no key. With read, the voice list and a single voice also show your organization's clones.

sttSpeech to text

Levelsnonewrite

stt:write
POST /api/v1/stt/transcribe
llmChat models

Levelsnonereadwrite

llm:read
GET /api/v1/models
llm:write
POST /api/v1/chat/completions
embeddingsEmbeddings

Levelsnonewrite

embeddings:write
POST /api/v1/embeddings
rerankRerank

Levelsnonewrite

rerank:write
POST /api/v1/rerank
accountBalance and usage

Levelsnoneread

account:read
GET /api/v1/balanceGET /api/v1/usage
api_keysAPI keys

Levelsnonereadwrite

api_keys:read
GET /api/v1/api-keysGET /api/v1/api-keys/{id}
api_keys:write
POST /api/v1/api-keysPATCH /api/v1/api-keys/{id}POST /api/v1/api-keys/{id}/revoke

write also opens everything read does.

Expiry, IP allowlist and spend limit

Expiry: after expires_at, the key answers 401 api_key_expired. Leave it empty for a key that never expires.

IP allowlist: up to 100 IPv4 or IPv6 addresses or CIDR ranges. A request from any other address answers 403 ip_not_allowed, and an empty list allows every address.

Monthly spend limit: the most the key may spend in a calendar month, in credits. A request that would go over it answers 402 spend_limit_exceeded.

A key is checked in the order of this table, and the first check that fails answers with its own code. So you can tell a key to replace from one to switch back on.

CodeWhat to do
invalid_api_key

401

The key is missing or unknown. Check the header and the key itself.
api_key_revoked

401

Revoked for good. Create a new key.
api_key_disabled

401

Switched off. Switch it back on to use it.
api_key_expired

401

Past its expiry. Give it a later one, or create a new key.
ip_not_allowed

403

The address is not on the allowlist. Add it, or call from a listed address.
insufficient_permissions

403

The key lacks the level this endpoint needs. Raise the level, or use another key.
spend_limit_exceeded

402

This month's limit would be passed. Raise the limit, or wait for the next month in UTC.

How the spend limit counts

Months are calendar months in UTC: the count starts again at 00:00 UTC on the first of each month.

A charge that lands exactly on the limit is allowed. Only one that would go over it is refused.

The check is best effort, like the balance check: requests already running when the limit is reached can take the key past it by their own cost.

Where a key can go over

  • Embeddings and reranking are checked against an estimate, then charged for the tokens the model reports, which can be more.
  • Synthesis jobs are checked when they are queued and charged when they finish, so a key can go over by as many jobs as it may have queued or running at once.

Speech to text is charged for the recording's real length, known only after the transcription. It is refused up front only when nothing is left of the limit. Otherwise the check follows the transcription, and one that would go over answers 402 and is not charged.

A spend limit belongs to one key. Keys made through the API get limits of their own, so together several keys can spend more than any one limit. Your organization's balance still caps them all.

What the allowlist checks

The allowlist checks the public address your request reaches NeuronAI from. Behind NAT, a VPN or your own proxy, that is the gateway's address, so list the gateway.

An entry matches only its own address family: 203.0.113.7 does not match ::ffff:203.0.113.7, and the reverse. List every address your requests can come from, IPv4 and IPv6.

A key with an allowlist can create keys only with entries from its own list, compared entry by entry: 10.0.0.0/24 does not count as part of 10.0.0.0/16.

Keys in the dashboard

Keys live in the dashboard, in Developers, then API keys.

A new key is shown once, in a dialog that a click outside does not close. Copy it then: NeuronAI keeps only a hash of it, so nobody can show it again.

After that, the list shows each key as nai_... and its last four characters, so you can tell keys apart. A connected app's key shows none, since nobody ever sees its secret.

To replace a key, or one you have lost, create a new key, move your applications to it, then revoke the old one.

Disable a key to stop it for a while, and enable it again later. Revoke it to stop it for good: a revoked key never works again.

Revoked keys stay on the page with their spend, behind “Show revoked keys”. Nothing deletes a key.

Keys held by the Telegram bot are marked “Telegram bot”. The bot creates them with only tts:write, voices:read, stt:write and account:read. They have no switch, because the bot replaces its key whenever it registers again. You can still change or revoke one.

Keys for MCP

An AI assistant needs tts:write, voices:write and stt:write, which cover every MCP tool. Give its key those and nothing else, and a monthly spend limit.

In Developers, then MCP, go to a CLI tab and set “Sign in with” to “API key”: “Create MCP key” there makes a key with these permissions.

When someone connects an app such as Claude or ChatGPT by signing in, NeuronAI creates a key for it, marked “Connected app”. It holds tts:write, voices:write and stt:write, and its secret is never shown to anyone.

Change its spend limit, IP allowlist and expiry like any key's, but keep the allowlist empty for Claude and ChatGPT, which call from their own servers. Its name and permissions stay as they were set when the app was connected. Its row offers “Disconnect” instead of revoke, which ends the key and the app's connection together.

To connect an assistant, follow the MCP server guide.

Team members and keys

Each key belongs to the member who created it. Removing a member from the organization revokes every key they hold, including the keys their keys created through the API.

A key created through the API outlives the key that created it: revoking the creator leaves the keys it made working, so revoke those yourself if you need to.

A key created through the API has no limits of its own: it shares your organization's totals with your other keys.

Managing keys from code

Five endpoints list, create, change and revoke your organization's keys. They need a key granted api_keys, and allow 60 requests a minute per user.

A key never grants more than it holds: no product above its own level, no full access from a restricted key, and no api_keys level above its own.

Nor looser limits: if it expires, the new key must expire no later; if it has a spend limit, the new key needs one no higher; if it has an allowlist, the new key may list only its entries. A breach answers 403 insufficient_permissions.

A change sends only the fields to change: permissions replaces the whole map, and null clears expires_at, allowed_ips or monthly_spend_limit. A change that gives a key more power is checked as if the key were new, so send its limits along with it.

A revoked key cannot be changed: that answers 409 conflict. The list includes revoked keys, newest first, and key ids are lowercase ULIDs. A key may revoke itself, which is how a rotation from code ends.

A connected app's key keeps its grant: a PATCH that sends its name, access or permissions answers 422 invalid_request, and revoking it disconnects the app.

API reference

Request fields, responses, prices and code samples for every endpoint, with a form that sends a real request.

Stored locally in your browser only.

API keys

Create, list, change and revoke your organization's API keys from code. Every call needs a key holding the `api_keys` permission: `read` to list and get, `write` to create, change and revoke. These endpoints allow 60 requests a minute per user.

GET
/v1/api-keys

Bearer

List API keys

Lists your organization's API keys, newest first, revoked ones included. Pages hold up to `limit` keys (1–100, default 50); pass a page's `next_cursor` as `cursor` to get the next. Key ids are lowercase ULIDs.

Parameters
Field Description
limit
query
integer | null
cursor
query
string | null
Responses
200
Success.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
dataRequiredApiKey[]
next_cursorRequiredstring | null
request_idRequiredstring

format: uuid

401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

422
The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
TypeScript SDK
import {NeuronAI} from "@naiuz/sdk";

const client = new NeuronAI();

for await (const key of client.apiKeys.list()) {
    console.log(key.id, key.name, key.masked_key);
}

Try it

Set your API key in the bar above to send authenticated requests.

limit
cursor

POST
/v1/api-keys

Bearer

Create an API key

Creates a key. `name` (1–80 characters) and `access` (`full` or `restricted`) are required. A restricted key holds exactly the levels in `permissions`; a full key holds every product, and its `permissions` may then name only `api_keys`. `allowed_ips` is a list of addresses or CIDR ranges, and `monthly_spend_limit` is in credits per calendar month (UTC). Answers 201 with the key and its `secret`. This is the only time the secret is ever shown, so store it now. The new key never holds more than the calling key. A restricted caller cannot create full keys or set a product above its own level, and the caller's own `api_keys` level caps the one it grants. The new key cannot have looser limits either: if the caller expires, the new key must expire no later; if the caller has a monthly spend limit, the new key needs one no higher; and if the caller has an IP allowlist, every entry of the new key's must appear in the caller's, compared entry by entry. A violation answers 403 `insufficient_permissions`. A spend limit applies to each key on its own. A key made through the API outlives the key that made it, and per-key rate and concurrency overrides are not inherited.

Request body
application/json
FieldDescription
nameRequiredstring

minLen: 1 · maxLen: 80

descriptionstring | null

maxLen: 500

accessRequiredApiKeyAccess
permissionsobject

Levels by product, such as `{"tts": "write"}`. On a `restricted` key a product left out is `none`. A `full` key already holds every other product at its highest level, so its map may name only `api_keys`.

expires_atstring | null

format: date-time

monthly_spend_limitnumber | null

In credits per calendar month (UTC), from 0 to 999999999999.99 with at most two decimals. Leave it out, or send `null`, for no limit.

allowed_ipsarray | null
Responses
201
Created.
application/json
HeaderDescription
Cache-ControlstringIncludes `no-store`: the answer holds the new key's secret, so no cache may keep a copy.
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
dataRequiredApiKey
request_idRequiredstring

format: uuid

401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), the client IP is not in its allowlist (`ip_not_allowed`), or the new key would hold more access, or looser limits, than the calling key allows (`insufficient_permissions`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

422
The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
cURL
# Needs a key holding api_keys:write.
curl -X POST "https://my.neuronai.uz/api/v1/api-keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "name": "CI",
    "access": "restricted",
    "permissions": {"tts": "write"},
    "expires_at": "2030-01-01T00:00:00Z"
  }'

# The response's data.secret is shown only this once — store it now.

Try it

Set your API key in the bar above to send authenticated requests.

application/json

GET
/v1/api-keys/{id}

Bearer

Get an API key

One key by `id`. A key of another organization answers 404 `not_found`.

Parameters
Field Description
idRequired
path
string
The key id: a lowercase ULID.
Responses
200
Success.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
dataRequiredApiKey
request_idRequiredstring

format: uuid

401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

404
No such key in your organization: `not_found`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
TypeScript SDK
import {NeuronAI} from "@naiuz/sdk";

const client = new NeuronAI();

const key = await client.apiKeys.retrieve("<key-id>");

console.log(key.name, key.masked_key);

Try it

Set your API key in the bar above to send authenticated requests.

Fill in the required parameter: id.

id*

PATCH
/v1/api-keys/{id}

Bearer

Change an API key

Changes a key. Send only the fields to change: `permissions` replaces the whole map, `enabled` switches the key on or off, and `null` clears `expires_at`, `allowed_ips` or `monthly_spend_limit` — `allowed_ips: []` clears the allowlist too. A change that gives the key more power is checked as if the key were being created. More power means a higher level or full access, switching the key on, a later expiry, a higher spend limit, or a wider allowlist. So send the key's limits along with such a change. A violation answers 403 `insufficient_permissions`. An app someone connected to the MCP server, such as Claude or ChatGPT, has a key of its own, named after the app with “(connected app)” at the end. That key keeps the name, access and permissions it was given when the app was connected: a change that sends any of them answers 422 `invalid_request`. Its description, limits, expiry and switch change like any key's. A revoked key cannot be changed: 409 `conflict`.

Parameters
Field Description
idRequired
path
string
The key id: a lowercase ULID.
Request body
application/json
FieldDescription
namestring

minLen: 1 · maxLen: 80

descriptionstring | null

maxLen: 500

accessApiKeyAccess
permissionsobject

Replaces the whole map. Levels by product, such as `{"tts": "write"}`. On a `restricted` key a product left out is `none`. A `full` key already holds every other product at its highest level, so its map may name only `api_keys`.

expires_atstring | null

format: date-time

monthly_spend_limitnumber | null

In credits per calendar month (UTC), from 0 to 999999999999.99 with at most two decimals. `null` removes the limit.

enabledboolean
allowed_ipsarray | null
Responses
200
Success.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
dataRequiredApiKey
request_idRequiredstring

format: uuid

401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), the client IP is not in its allowlist (`ip_not_allowed`), or the change would give the key more access, or looser limits, than the calling key allows (`insufficient_permissions`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

404
No such key in your organization: `not_found`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

409
The key is revoked and cannot be changed: `conflict`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

422
The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
TypeScript SDK
import {NeuronAI} from "@naiuz/sdk";

const client = new NeuronAI();

const key = await client.apiKeys.update("<key-id>", {enabled: false});

console.log(key.enabled);

Try it

Set your API key in the bar above to send authenticated requests.

Fill in the required parameter: id.

id*
application/json

POST
/v1/api-keys/{id}/revoke

Bearer

Revoke an API key

Revokes a key for good: it stops working at once and can never be switched back on. Its usage history stays. A key may revoke itself, to rotate. Revoking the key of an app connected to the MCP server also disconnects the app, ending its sign-in. Answers 204.

Parameters
Field Description
idRequired
path
string
The key id: a lowercase ULID.
Responses
204
No content
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

404
No such key in your organization: `not_found`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
cURL
# Rotate a key safely: create the replacement first, move your apps to
# its secret, and only then revoke the old key below.
curl -X POST "https://my.neuronai.uz/api/v1/api-keys/<key-id>/revoke" \
  -H "Authorization: Bearer <your-api-key>"
# 204 No Content

Try it

Set your API key in the bar above to send authenticated requests.

Fill in the required parameter: id.

id*