API keys & permissions
Every surface authenticates the same way: a Tenzro Labs API key sent as a bearer token. The key is the primary identifier — it names the party calling, you or one of your agents, and everything else follows from it.
Authorization: Bearer tzl_...Create and revoke keys on the API keys page, or with the Platform API using a key that has manage (the MCP server only lists keys: agents never create them). The secret is shown once; only a hash is stored. Revocation takes effect on the next request.
Party — who a key identifies
| Key issued to | Identity | Notes |
|---|---|---|
| You | did:tenzro:human:… | Rooted in your passkeys. Can hold any permission. |
| An agent | did:tenzro:machine:… | Inference only. Usage counts against the agent's limits and appears as the agent. See Identity & agents. |
Permissions — what a key can do
| Permission | Grants |
|---|---|
inference | Call models through the Inference API, billed to the account's credit. |
read | View the account through the Platform API and MCP: balance, activity, orders, keys, plans, rentals, tickets. |
manage | Create orders and start payment, create and revoke keys, redeem tickets, cancel or resume plans. Implies read in the UI. |
Each service adds its own scopes to the same keys, so one key list covers everything: there are no separate credentials per service.
| Scope | Grants |
|---|---|
datasets:read | Datasets: list datasets, items, versions; download exports. |
datasets:write | Datasets: add and review items, cut versions. |
fieldwork:read | Fieldwork: projects, participants, submissions. |
fieldwork:write | Fieldwork: create and change projects, review submissions. |
voices:speak | Voices: one-shot speech. |
voices:batch | Voices: dataset jobs. |
voices:train | Voices: custom voices from consented references. |
voices:admin | Voices: manage custom voices and jobs. |
vision:analyse | Vision: describe, read, ask, detect; keep inputs in Datasets. |
vision:generate | Vision: image and video generation. |
vision:batch | Vision: run models over an image Dataset. |
wallets:read | Wallets: org, members, agents, approvals, webhooks, headless wallets, usage. |
wallets:write | Wallets: request agent and headless wallet changes, webhooks, org settings. |
New keys default to inference only, and keys made before a service existed hold none of its scopes until you grant them on the API keys page, where each of your keys can be edited. A write scope implies the matching read. A key can only create keys with permissions it holds itself. Changes and revocations apply from the key's next request. Wallets takes the same keys: wallets:read and wallets:write make a key your server credential there (see Wallets); Wallets checks each key with the Platform, so changes reach it within 30 seconds.
manage key cannot move money on its own: paying an order returns a Stripe Checkout link or a stablecoin deposit address that a person completes. It can still spend existing credit by minting inference keys, so store it like a password.Access — where inference can go
| Access | Behaviour |
|---|---|
| All machines (default) | Requests route across every healthy machine serving the model. Uses machine-pinned credit for the serving machine first, then credit usable anywhere. |
| One machine | Requests only go to that machine. Useful for data residency or consistent latency. |
| Plan | Pinned to the plan's machine, subject to the plan's rate limit and model list; draws from the plan's included credit first. No machine offers plans on testnet. |
| Rental | Authenticates against a rented slice for the rental's term. Usage is prepaid. No machine offers rentals on testnet. |
Authentication errors
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated | No key was sent to an endpoint that needs one. |
| 401 | invalid_key | The key is malformed, unknown, or revoked. |
| 403 | forbidden | The key lacks the permission this operation needs. |
curl https://api.tenzro.xyz/me -H "Authorization: Bearer $TENZRO_API_KEY"
{"error": {"code": "forbidden", "message": "This key lacks the \"read\" permission. ..."}}Good practice
- Use separate keys per app and environment so one can be revoked without touching the others.
- Give production services
inferenceonly; keepmanagekeys for automation you control. - Pin keys to a machine when the workload must stay in one region.
- Check
last_used_aton the keys list and revoke keys that are no longer used.