Skip to main content
Are you an AI agent, or building one?Start with Authentication for AI agents — it points to the machine-readable manifest an agent can fetch and follow on its own.
Every agent-callable Nevermined endpoint is authenticated by a single header:
That’s the whole contract. Getting the key is the only interesting part — and depending on whether a human is in the loop and whether a browser is available, there’s a path for each case.

​
The one rule

Bearer in the Authorization header is the only accepted form — not a query parameter, not a body field. Keys are environment-prefixed (sandbox:… / live:…); send the whole string, prefix included.

​
Environments

Both are fully independent: an account, key, and balance in one do not exist in the other. Start in sandbox.

​
What a Nevermined key actually is

A Nevermined API key is not an opaque random string — it’s an encrypted, signed JWT that carries an on-chain session key. That has two consequences worth internalizing before you integrate:
  • The real enforcement boundary is on-chain. The account’s smart-account kernel rejects any call outside the session key’s policy. The API-layer permission flags a key carries (canRegister / canOrder / canMint / canBurn) are a derived, advisory projection of that on-chain policy — they tell you what the key was minted to do, not what a request-time guard will check.
  • Don’t hand-roll a key. Because the credential wraps a session key, minting one is the SDK’s job. Use @nevermined-io/payments (TypeScript) or payments-py (Python), or have a human create one for you in the app (Profile → API Keys).
Scope is deliberately not advertised in our authorization-server metadata — you won’t find scopes_supported. We don’t publish a scope vocabulary the API layer doesn’t itself enforce. Treat the on-chain policy as authoritative.

​
Which path do I use?

SDK key

You can run an SDK and manage your own identity. The simplest path — the SDK mints a key directly. See Get a Nevermined API key.

Device flow (RFC 8628)

You’re a headless agent with no browser, but a human can approve for you. Approval is collected without a browser on your side — typically ending in an NVM API key bound to the approver. See Device flow.

Authorization Code + PKCE

You’re a browser-based MCP client (Cursor, Claude). The user approves in a browser — typically to obtain an x402 payment permission for a specific agent. See Authorization Code.
The credential you receive is chosen by the requested resource, not by the grant. A resource (RFC 8707 audience) matching this API’s host mints an NVM API key; any other resource mints an x402 payment permission. An account_access consent always yields an API key; with no resource, a delegation-backed binding yields an x402 permission and a plan-only binding yields an API key. The two grants differ only in how the human approves — Authorization Code in a browser, the device flow without one — so pick the grant by your environment and the resource by the credential you need.

​
Discovery

Everything the ceremony needs is advertised in standards-based metadata. If a capability is absent from these documents, it does not exist — don’t infer it. Because a transport now mints a credential this API accepts, discovery reflects it: the Protected Resource Metadata names this issuer in authorization_servers, and a genuine authentication 401 carries an RFC 6750 WWW-Authenticate: Bearer resource_metadata="…" challenge pointing at it.

​
Reading a 401

A 401 is usually a missing, malformed, or invalid key — not a hint to go discover something. It isn’t always an authentication problem, though: a few endpoints return 401 when you’re authenticated but lack access to a specific resource. Distinguish by the error body’s category field:
  • category: validation → fix your request (a malformed or missing parameter).
  • category: auth → fix your credential.
  • category: business or integration → you reached something that isn’t yours.
  • category: internal → not your fault; retry, or report it with the correlation id.
The x-correlation-id header is always present — quote it (and the BCK.* code, if any) when asking for help. See the API error codes.

​
What needs a human, and why

Three things require a person in the loop. None is an oversight:

Card enrolment

The card number never reaches Nevermined — it’s tokenized inside a VGS iframe in the browser. There is no server-to-server path, by design (PCI scope). You drive the hand-off; see Enroll a card.

First account

First login at nevermined.app is a browser flow (Privy — Google or email OTP). A human onboards, then hands you a key.

Visa delegations

A provider=visa delegation needs a per-delegation FIDO/passkey device-binding ceremony in the browser. You can use an existing Visa delegation but can’t create one. Stripe, Braintree, and crypto delegations you create yourself.
Once a card is enrolled, spending on Stripe, Braintree, and crypto delegations is yours to drive with no further browser step — create a delegation and reuse its id on your x402 requests. Visa is the exception noted above: an existing Visa delegation you can use, but creating one needs the per-delegation device-binding ceremony in the browser.

​
Next steps

Authentication for AI agents

The machine-readable manifest an agent fetches and follows.

Device flow (RFC 8628)

Get an API key with a human’s approval, no browser on your side.

Authorization Code + PKCE

Browser-based MCP clients paying for a specific agent.

Connected agents

List and revoke the agents a user has authorized.

Related topics

For AI agents — read this firstGet a Nevermined API keyDevice flow (RFC 8628)OAuth 2.1 Authorization Code