# API keys and scopes

> Which key each call needs: the intents, read, halt and execute scopes, an execute key's own limits, rate limits, and what no key can do.

Canonical page: https://nevarn.com/docs/keys
Updated: 2026-11-02

Every call your bot makes carries one API key, and a key does only what its scopes say. A bot's usual key has intents, read and halt. A key that should place orders also has execute, which an owner ticks by name with the key's own limits: orders a minute, the largest order and a 24-hour total.

> Keys are shown once, when they are minted, and kept only as a hash. Store yours in a secret manager or an environment variable; never in your bot's code, an intent or a prompt.

## Mint a key

1. Sign in to your developer dashboard (https://dev.nevarn.com, with your email and password) or, on a customer account, the console's Commerce panel. You need to be the account's owner or an admin.
2. On the API keys card, press For a bot. It ticks intents, read and halt.
3. Tick execute too only if the bot should place orders, and set its limits (the card proposes 6 orders a minute, 100 USDC an order and 1,000 USDC a day; change them before minting).
4. Give the key a label, press Create key and copy the secret. It starts nvk_.

```bash
export NEVARN_API_KEY=nvk_…
curl -s https://api.nevarn.com/machine/mandate -H "Authorization: Bearer $NEVARN_API_KEY"
```

## Scopes

| Scope | Lets the key | Routes | SDK, MCP |
| --- | --- | --- | --- |
| intents | Propose intents for a shadow ruling. Nothing is sent to a venue. | POST /machine/intents | proposeIntent, propose_intent |
| execute | Have intents executed under Decionis policy, within the key's limits: on paper in Sandbox, live in Production | POST /machine/executions, GET /machine/executions/{id} | executeIntent, getExecution, execute_intent, get_execution |
| read | Read your bounds and your execution receipts | GET /machine/mandate, GET /machine/receipts/{id} | getMandate, getReceipt, get_mandate, get_receipt |
| halt | Turn all of your signing off and stop your bots' unsent executions. It cannot resume. | POST /machine/halt | halt |
| invoices | File supplier invoices for your payables policy to decide | POST /machine/invoices | requestSpend, request_spend |
| facilitator | Verify and settle machine payments for your resources | POST /machine/verify, POST /machine/settle | Not in the SDKs |

A key with no scope, an unknown scope, or execute without its limits is refused at minting. A call with a key that lacks the route's scope answers 403; an unknown or revoked key answers 401.

> A password sign-in reaches the developer dashboard: your keys, your bots' rulings, usage and plan. It can mint keys with intents, read and halt, and execute while the account is in Sandbox. Keys with invoices or facilitator, the Production switch, and anything that moves funds need a wallet sign-in in the account console.

## What no key can do

No scope resumes signing, changes a limit, mints or revokes a key, adds or verifies a supplier, approves a payment or switches the account between Sandbox and Production. Those take a person signed in to the console or the dashboard, never a key, so a leaked key can propose, execute within its own limits or stop - never widen what it may do.

## An execute key's limits

| Limit | What it counts | Bounds |
| --- | --- | --- |
| Orders a minute | Executions the key asked for in the last minute | 1 to 60 |
| Largest order | One order's notional in USDC: a BUY's maker amount, a SELL's taker amount | Up to the 24-hour total |
| 24-hour total | The notional of the key's executions over a rolling 24 hours | Above zero |

- The limits are stated when the key is minted and fixed for its life. To change them, mint a new key and revoke the old one.
- Only polymarket and sports intents can be executed: their terms state the order's size in USDC, which the limits count. capital and arbitrage intents are refused with strategy_not_executable.
- Your account's own largest-order limit, its signing grants and its kill switch apply on top of the key's limits.
- A key with execute minted from a password sign-in executes in Sandbox only. If the account is in Production, its executions are refused with key_minted_without_wallet, at intake and again before the order is prepared and sent. To make a key live, an owner mints it from the account console with a wallet sign-in.
- Over a limit, nothing is ruled, filled or queued: the call answers 409 with key_order_limit_exceeded or key_daily_limit_exceeded, or 429 key_rate_limit_exceeded for the minute window.
- Each key on the dashboard and in the console shows how it was minted. The console's Production readiness lists every execute key Production would refuse, before anyone switches.

## Rate limits

| Route | Per key, per minute |
| --- | --- |
| POST /machine/intents | 60 |
| POST /machine/executions | 60, and the key's own orders a minute |
| GET /machine/executions/{id} | 120 |
| GET /machine/mandate | 60 |
| GET /machine/receipts/{id} | 60 |
| POST /machine/halt | 10 |

Over a rate limit the call answers 429 with a Retry-After header in seconds; the SDKs raise RateLimited with retryAfter set.

## Keeping keys safe

- The SDKs and the MCP server take the key only from their constructor or NEVARN_API_KEY, never print it, and refuse a session token in its place.
- Give each bot its own key, so its rulings, executions and governed actions are counted per key and one can be revoked alone.
- Revoke a key from the same card. A revoked key answers 401 from its next call.