Authorization: Bearer … on every call. (“Usual case” because the credential is actually selected by the resource you request — omit it (as below) or use this API’s host for an API key; a non-API resource would mint an x402 permission instead. See which credential you get.)
This is the “claim ceremony” an agent can use on its own. Both the
device_authorization_endpoint and the urn:ietf:params:oauth:grant-type:device_code grant are advertised in the RFC 8414 metadata — but discovery alone isn’t enough to start: you still need a pre-registered client_id and an agent_id (below).Prerequisites
- A pre-registered
client_id. Connectors are onboarded out of band — there is no self-service dynamic client registration, and the metadata deliberately omits aregistration_endpoint. An unregisteredclient_idis rejected withBCK.OAUTH.0016. If you don’t have one, ask Nevermined to register your client. - An
agent_id— the agent you want authorized. It’s required today; an absentagent_idis rejected withBCK.OAUTH.0018(account-level authorization with noagent_idis a follow-up).
The ceremony
1
Request a device + user code
device_code is your machine secret (opaque — poll with it). user_code is what the human types. interval is the minimum seconds between polls.2
Send the human to approve
Show them the
verification_uri and user_code (or the verification_uri_complete as a link/QR). They open it, sign in, review who is asking and for what, and approve. The verification page resolves what they see — the connector name, target agent, and scope — via POST /oauth/device/details. That endpoint requires the human’s Nevermined API key (it’s the browser verification surface), so your keyless agent can’t call it to pre-preview; just hand off the user_code and poll.3
Poll for the credential
interval — the poll endpoint is rate-limited. Branch on the top-level error:A real HTTP
429 (rate limit) is distinct from the slow_down grant error and does not appear in the error field — the poll endpoint is throttled per client IP (~60/min for device polls, shared across every concurrent ceremony from the same host, not per device_code). Treat a 429 like slow_down: back off and resume. Note the throttler sends Retry-After-short / Retry-After-long headers rather than a plain Retry-After.On approval you receive your credential:4
Use the key
access_token is your NVM API key. Send it as Authorization: Bearer <access_token> on every /api/v1 call. Keep the refresh_token to mint a fresh key without another human step (RFC 6749 refresh grant).