API keys and scopes

Create keys with only the access they need, pin them to a user, and cap what they spend.

A platform API key lets your server act for your account. Create keys in the developer console under API keys. Each key has a name, the scopes it may use, and optionally a monthly spend cap, an expiry and a user it's pinned to. Creating one accepts the Developer Terms and the Acceptable Use Policy.

The console's Quickstart gives a coding agent a key without showing it the key: its prompt carries a one-time setup code (30 minutes), and the agent's one command trades it for a key that goes from the response straight into the project's .env:

curl -fsS -X POST https://api.noclick.com/v1/setup -d code=nc_setup_... >> .env

That key is named "Coding agent" and has the console's Full access. A code works once; a used or expired one fails with 410.

A key starts with nk_live_ and is shown once, when you create it. After that the console shows only its prefix, like nk_live_ab12, which is also how you filter activity by key.

Scopes

Scope	Lets the key
`users`	create, read, update and suspend users, and mint sessions
`credentials:request`	create and delete connections, send connect links, import credentials
`credentials:use`	list and verify connections and run integration operations through them
`credentials:token`	read a connection's OAuth access token
`tools`	get toolkit definitions and run tool calls
`humans`	ask, approve and notify people
`agents`	create, change and message agents
`channels`	open and use channels
`inbox`	create and read inboxes, and reply
`phone`	buy phone numbers, route them and place calls
`ai`	call AI models; talking to an agent as a model takes `agents`
`sandboxes`	start and use sandboxes
`operations`	list operations, count them, and read an agent turn's tool calls
`usage`	read spend and the activity logs
`policy`	read and set policy
`brand`	read and set your brand
`webhooks`	manage webhook endpoints and read events
`webhooks:reveal`	read a webhook's signing secret; a key with `*` doesn't have it unless it's named too
`mcp_servers`	create and manage hosted MCP servers
`storage`	create buckets, read and write their files, and mint signed links
`volumes`	create volumes, and read and write their files
`dicts`	create dicts, and read and write their keys
`queues`	create queues, and send, receive and settle messages
`secrets`	create secrets and set their values, which no key can read back
`workflows`	run workflows and give them endpoints
`apps`	create and deploy apps, and set their bindings, secrets, schedules and app services
`repos`	create repos, commit, and mint clone links
`databases`	create and query databases, migrate, restore and branch them
`domains`	search, connect and manage domains
`domains:buy`	buy and renew domains, which charges your account
`browsers`	start browsers and manage browser profiles

Scopes for cards

Scope	Lets the key
`cards`	create and manage cards and read their transactions
`cards:reveal`	hand out a card's number: a reveal page or a purchase's number

The console offers sets of these: Full access is every scope except the three that read secrets, credentials:token, cards:reveal and webhooks:reveal; Read-only is usage and operations; or pick your own. Only grant credentials:token to code that must call providers directly, since it can read your users' access tokens, cards:reveal only to code that hands a card's number to a person or announces purchases, and webhooks:reveal only to the receiver that verifies deliveries.

A call a key's scopes don't cover fails with noclick.PermissionDenied. Reading, waiting on and cancelling one operation by its id needs no scope.

Pin a key to a user

A key pinned to a user always acts for that user, without as_user, and can't act for any other: naming another user fails with noclick.PermissionDenied. Use one for a service that only ever works for one customer.

For code in a browser, don't use a pinned key: mint a session, which expires.

Cap a key's spend

A key's monthly spend cap limits everything done with that key. Once it's reached, calls with the key fail with noclick.SpendCapExceeded until the next month or until you raise the cap. You can change a key's name and cap at any time in the console.

Publishable keys

A web page can't hold a secret key: anyone can read it from the page. A publishable key starts with nk_pub_ and is safe to ship in a page, because it can call only the endpoints you've made public and listed on it, such as a shared agent's chat or a workflow's public endpoint. It reads nothing else, and spends only through those endpoints.

Create one in the console under API keys, choosing Publishable as the key type. For each one you pick:

Endpoints: the public endpoints it may call. A key with none calls nothing.
Per-visitor limit: how many calls one visitor (by IP address) may make a minute; more fail with 429 and noclick.RateLimited. The default is 20.
Allowed origins: the sites that may use it from a browser, like https://acmebooking.com. A call from any other origin, or with none, fails with 403 and noclick.PermissionDenied; with none listed, any site may.

A publishable key is shown in full at any time, since it isn't a secret, and it still has a monthly spend cap: the turns and runs its visitors start count against it, as well as against your other caps. Change its endpoints, limit and origins from its row's menu; calls to an endpoint you take off it, or one that stops being public (an agent whose page you turn off), are refused at once.

A visitor never learns about your account's money or rules: a call a cap, your balance or your policy stops answers 409 with not_available, and the reason shows in your activity instead. A call for a user whose spending you paused answers 402 spending_paused with only what you wrote for that user: its user_message, action and since. Any other route refuses a publishable key with 403. To act as one of your users in the browser, with their own agents and connections, mint a session instead.

Revoke a key

Revoking a key stops it at once, along with every session it minted. To rotate a key, create the new one, deploy it, then revoke the old one.

Scopes#

Scopes for cards#

Pin a key to a user#

Cap a key's spend#