Nevermined OAuth API
The OAuth API from Nevermined — 3 operation(s) for oauth.
The OAuth API from Nevermined — 3 operation(s) for oauth.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nevermined-app:nevermined-app-oauth-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: NVM BACKEND OAuth API
description: ''
version: 1.103.0
contact: {}
servers:
- url: https://api.live.nevermined.app
tags:
- name: OAuth
paths:
/oauth/token:
post:
description: OAuth 2.1 token endpoint. Validates the authorization code and PKCE `code_verifier`, then returns an access token (JWT) in the OAuth standard format. The single-use, time-limited code already carries the user identity, so no user authentication is required. Public endpoint — no authentication required.
operationId: OAuthController_token
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequestDto'
responses:
'200':
description: Access token response
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponseDto'
'400':
description: Bad Request - Invalid code, PKCE validation failed, or other errors
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthGrantErrorDto'
summary: Exchange authorization code for access token
tags:
- OAuth
/oauth/device_authorization:
post:
description: 'Starts the device ceremony for a browserless agent: returns a device_code (poll /oauth/token with it), a human-typeable user_code, and a verification_uri where a human approves. Public endpoint — no authentication required.'
operationId: OAuthController_deviceAuthorization
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceAuthorizationRequestDto'
responses:
'200':
description: Device authorization response (RFC 8628 §3.2)
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceAuthorizationResponseDto'
'400':
description: Bad Request - unknown client or missing agent_id
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthGrantErrorDto'
'404':
description: Not Found - Agent not found
summary: RFC 8628 device authorization request
tags:
- OAuth
/oauth/revoke:
post:
description: Revokes the AgentBinding behind the supplied credential (NVM API key or x402 access token), invalidating every credential minted from it. Idempotent — always returns 200, including for an unknown or already-revoked token. Public endpoint.
operationId: OAuthController_revoke
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeRequestDto'
responses:
'200':
description: Token revoked (or already revoked / unknown).
summary: Revoke a credential (RFC 7009)
tags:
- OAuth
components:
schemas:
TokenResponseDto:
type: object
properties:
access_token:
type: string
example: eyJhbGciOiJFUzI1NksifQ...
description: Access token (JWT)
token_type:
type: string
example: Bearer
description: Token type
enum:
- Bearer
default: Bearer
expires_in:
type: number
example: 3600
description: Token expiration time in seconds
refresh_token:
type: string
example: nvm_rt_Zm9vYmFyYmF6...
description: 'Refresh token (#2396) — present it to POST /oauth/token with grant_type=refresh_token to re-mint the credential from the same binding without re-authorizing (RFC 6749 §6). One-time use: rotated on each refresh. Rarely absent on the authorization_code exchange if refresh-token issuance failed after the access token was already minted (the exchange still succeeds).'
scope:
type: string
example: calendar contacts
description: Scope of the access token
required:
- access_token
- token_type
- expires_in
DeviceAuthorizationRequestDto:
type: object
properties:
client_id:
type: string
example: fleet
description: The registered OAuth client id — a connector or the first-party webapp. An unregistered client is rejected (#2235 G3).
agent_id:
type: string
example: agent-123
description: Target agent the ceremony binds to a human. Distinct from client_id (the OAuth client) and resource (the RFC 8707 audience). Account-level (omitted) is a follow-up (#2541).
resource:
type: string
example: https://api.nevermined.app
description: RFC 8707 resource (audience) the credential is scoped to. Omit for the default API key. Device ceremonies currently support only API-host resources (no x402/delegation-backed resource — that is a follow-up); a non-host resource is rejected at /oauth/token.
scope:
type: string
example: openid
description: RFC 8628 §3.1 optional scope.
required:
- client_id
DeviceAuthorizationResponseDto:
type: object
properties:
device_code:
type: string
description: The machine secret the agent polls /oauth/token with (opaque).
user_code:
type: string
example: BCDF-GHJK
description: The short code the human types at the verification URI.
verification_uri:
type: string
example: https://nevermined.app/oauth/device?network=live
description: Where the human goes to enter the user_code and approve.
verification_uri_complete:
type: string
example: https://nevermined.app/oauth/device?network=live&user_code=BCDF-GHJK
description: 'RFC 8628 §3.3.1: verification_uri with the user_code pre-filled (for a QR/link).'
expires_in:
type: number
example: 600
description: Seconds until the device_code/user_code expire.
interval:
type: number
example: 5
description: Minimum seconds the agent must wait between token polls.
required:
- device_code
- user_code
- verification_uri
- verification_uri_complete
- expires_in
- interval
TokenRequestDto:
type: object
properties:
grant_type:
type: string
example: authorization_code
description: Grant type
enum:
- authorization_code
- refresh_token
- urn:ietf:params:oauth:grant-type:device_code
code:
type: string
example: abc123...
description: Authorization code from /oauth/authorize. Required for grant_type=authorization_code.
redirect_uri:
type: string
example: cursor://oauth/callback
description: Redirect URI (must match the authorize request). Required for authorization_code.
client_id:
type: string
example: fleet
description: 'The registered OAuth client id (connector) — the same value sent to /oauth/authorize. #2235 G3: this is the OAuth client, NOT the agent id.'
code_verifier:
type: string
example: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
description: PKCE code verifier. Required for grant_type=authorization_code.
refresh_token:
type: string
example: nvm_rt_Zm9vYmFy...
description: Refresh token. Required for grant_type=refresh_token (#2396).
device_code:
type: string
example: a1b2c3...
description: Device code from /oauth/device_authorization. Required for grant_type=urn:ietf:params:oauth:grant-type:device_code (#2318 B).
resource:
type: string
example: https://mcp-server.example.com
description: MCP Server URI (resource identifier)
required:
- grant_type
- client_id
OAuthGrantErrorDto:
type: object
properties:
code:
type: string
description: Nevermined error code for the grant failure. The device-polling family is BCK.OAUTH.0021 (pending) / 0022 (slow down) / 0023 (expired) / 0024 (denied); other BCK.OAUTH or BCK.HTTP codes may appear for code, PKCE, or request-validation failures.
example: BCK.OAUTH.0021
httpStatus:
type: number
description: HTTP status code
example: 500
message:
type: string
description: Human-readable error message describing what went wrong
example: Unable to initialize Nevermined instance
details:
type: string
description: Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise.
example: Hash JWT is not signed by the node account
error:
type: string
description: 'RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error — branch on THIS, not the Nevermined `code`. The device grant emits `authorization_pending` (keep polling), `slow_down` (back off), `expired_token` / `access_denied` (stop). NOT an exhaustive set: a request-validation failure carries the framework value `Bad Request`, and a rejected / expired code omits `error` entirely. `invalid_grant` / `invalid_request` are the RFC names for a rejected or malformed grant but are reserved — not emitted today.'
example: authorization_pending
hint:
type: string
description: Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look.
example: Verify the wallet has sufficient balance and that the plan is active.
docsUrl:
type: string
description: Permalink to the docs page describing this error code.
example: https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008
category:
type: string
description: Coarse classification of the failure, useful for client-side branching without parsing the message.
enum:
- validation
- auth
- business
- integration
- internal
example: integration
retryable:
type: boolean
description: Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way.
example: true
correlationId:
type: string
description: Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues.
example: a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9
uuid:
type: string
description: Per-error UUID generated at construction. Useful for log correlation.
example: e-550e8400-e29b-41d4-a716-446655440000
date:
type: string
description: ISO timestamp at which the error was constructed.
example: '2026-05-09T12:34:56.789Z'
format: date-time
params:
type: string
description: JSON-stringified contextual parameters supplied at the throw site (e.g. IDs, state). Always a string in the wire format — parse with JSON.parse if needed.
example: '{"planId":"43298432984329","reason":"Invalid configuration"}'
required:
- code
- httpStatus
- message
RevokeRequestDto:
type: object
properties:
token:
type: string
description: The credential to revoke (an NVM API key or an x402 access token).
token_type_hint:
type: string
description: RFC 7009 token_type_hint. Advisory only — resolution does not depend on it.
required:
- token
securitySchemes:
Authorization:
scheme: bearer
bearerFormat: JWT
type: http