Skip to navigation

Authentication

Bearer API keys, scoped to an organization.

Every request carries an API key in the Authorization header:

Authorization: Bearer nl_live_...

Keys are issued per organization from the dashboard.

Key format

A key is a prefix followed by 32 bytes of randomness encoded in base62 — 51 characters in total:

nl_live_YxQFoF6p2xKvStMzWhYhwPMNSlEnWTwzYL83OJCbyTo
└──────┘└─────────────────────────────────────────┘
prefix 43 base62 characters (32 random bytes)

Live and test keys

You choose the mode when you create a key in the dashboard.

ModePrefixBehavior
Livenl_live_Real transcription. Each request is billed against the organization’s wallet.
Testnl_test_An instant dummy result. Free. The response has the same shape as a live response.

Use a test key to build and check your integration without cost. Switch to a live key to get real transcripts. See test keys for how a test key differs.

Only the SHA-256 hash of a key is stored, so the plaintext is shown once at creation and cannot be recovered afterwards. Lose it and you mint a new one. The dashboard and the API only ever show the first 12 characters (nl_live_YxQF), which is enough to tell your keys apart and useless on its own.

A key carries its organization, its scopes, an optional expiry, its own rate limit, and a last-used timestamp.

Test keys

A key that starts with nl_test_ is a test key. It never runs the model and never costs anything, so you can wire up an integration without spending balance or GPU time.

A test key answers the same way a live key does, with these differences:

  • The transcript is a dummy. It is the same text for the same audio length and language, and its length follows the duration of your audio.
  • The answer takes about one second.
  • The response has the header x-nyra-test-mode: true. A live key never sets it.
  • x-nyra-cost-usd is 0.000000. No wallet hold is placed and no ledger entry is written.

Everything else is identical. The body has the same fields: verbatim, intended, word timestamps for both, alignment, duration, language and usage. Your request is checked the same way, so a missing model, an unsupported language, an oversized file or a file that is not audio gives the same error as with a live key. The request still appears in the request explorer, marked as not billable.

curl https://api.nyra-labs.com/v1/audio/transcriptions \
-H "Authorization: Bearer nl_test_..." \
-F model=crisperwhisper-v2 \
-F language=en \
-F file=@recording.wav -i | grep -i x-nyra-test-mode
# x-nyra-test-mode: true

Do not use a test key to judge transcription quality. For that, use a live key or the dashboard playground. Playground runs are billed like live requests.

Errors

Authentication failures return the standard error envelope with type: "authentication_error" and HTTP 401.

No key at all:

{
"error": {
"message": "You didn't provide an API key. You need to provide your API key in an Authorization header using Bearer auth (i.e. Authorization: Bearer nl_live_...). You can find your API key at https://platform.nyra-labs.com/api-keys.",
"type": "authentication_error",
"param": null,
"code": "missing_api_key"
}
}

A key that is unknown, malformed, revoked or expired. The key is echoed back redacted to its first 8 and last 4 characters, so you can tell which key failed without the error log becoming a place credentials leak:

{
"error": {
"message": "Incorrect API key provided: nl_live_…byTo. You can find your API key at https://platform.nyra-labs.com/api-keys.",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}

All four causes return the same message. Distinguishing “unknown” from “revoked” would confirm to whoever holds a leaked key that it used to be real.

Scopes

A key can be narrowed to a subset of the API. The available scopes are:

ScopeGrants
transcriptions:writePOST /v1/audio/transcriptions
models:readGET /v1/models, GET /v1/models/{model}

A key created without scopes is unrestricted — that is the default. Narrowing is opt-in, and it is worth doing for any key that leaves your own infrastructure: a key that only transcribes cannot enumerate the catalogue, and a key that only reads the catalogue cannot spend money.

Calling an endpoint your key lacks the scope for returns HTTP 403:

{
"error": {
"message": "You have insufficient permissions for this operation. Your API key is missing the 'transcriptions:write' scope. Grant it at https://platform.nyra-labs.com/api-keys, or use a key with no scope restrictions.",
"type": "permission_error",
"param": null,
"code": "insufficient_scope"
}
}

Rate limits

Limits are per key and reset on a rolling one-minute window. The default is 600 requests per minute; a lower or higher limit can be set on each key in the dashboard. Every /v1 response carries:

HeaderMeaning
x-ratelimit-limit-requestsRequests allowed in the window
x-ratelimit-remaining-requestsRequests left in the current window
x-ratelimit-reset-requestsTime until the window resets, e.g. 43s
retry-afterSeconds to wait. Sent on 429 only

Counters are shared across every API instance, so a limit is a limit no matter which server answers.

Exceeding the limit returns HTTP 429:

{
"error": {
"message": "Rate limit reached for requests. Please slow down or contact support to raise your limit.",
"type": "rate_limit_error",
"param": null,
"code": "rate_limit_exceeded"
}
}

A request that arrives with no usable key is limited by client IP instead, at a deliberately low rate — it is on its way to a 401 regardless.