API Reference¶

Nexus exposes two API surfaces: the Gateway API, which agents and applications call, and the Broker API, which is internal and used only by the Gateway and administrative tooling.

The full OpenAPI 3.0 specification is at openapi.yaml. The v1 surface is frozen — no breaking changes without a major version bump and a deprecation period.

Gateway API¶

The stable, public-facing surface for all agent integrations. Versioned at /v1.

Connection endpoints¶

Method	Path	Description
`POST`	`/v1/request-connection`	Initiate an OAuth handshake or static credential capture
`GET`	`/v1/check-connection/{id}`	Poll connection status
`GET`	`/v1/token/{id}`	Retrieve credentials for an active connection
`POST`	`/v1/refresh/{id}`	Force a token refresh for a connection
`DELETE`	`/v1/connections/{id}`	Revoke a connection and destroy its stored credential
`GET`	`/v1/capture-schema`	Fetch the credential schema for a static provider
`POST`	`/v1/capture-credential`	Submit credentials for a static provider

Agent session endpoints¶

Method	Path	Description
`POST`	`/v1/agent-sessions`	Request a scoped session for a registered agent
`GET`	`/v1/agent-sessions/{id}`	Check session status and metadata
`DELETE`	`/v1/agent-sessions/{id}`	Close a session and revoke the token
`POST`	`/v1/agent-sessions/obo`	Request an OBO session tied to a user context token

Provider endpoints¶

Method	Path	Description
`GET`	`/v1/providers`	List all registered providers
`GET`	`/v1/providers/metadata`	Grouped metadata for frontend rendering
`POST`	`/v1/providers`	Register a new provider
`GET`	`/v1/providers/{id}`	Get provider by ID
`PATCH`	`/v1/providers/{id}`	Update specific fields of a provider
`DELETE`	`/v1/providers/{id}`	Delete a provider

System¶

Method	Path	Description
`GET`	`/v1/health`	Health check — returns `200 OK` when ready

Authentication¶

Connection and token endpoints do not require authentication headers. Access control is enforced by the connection_id — only callers holding a valid connection ID can retrieve its credentials. Treat connection_id values as session tokens.

Provider management and agent session endpoints require the X-API-Key header.

Token response shape¶

GET /v1/token/{id} returns a structured payload regardless of credential type:

{
  "strategy": { "type": "oauth2" },
  "credentials": {
    "access_token": "eyJ...",
    "expires_at": 1715000000
  },
  "scope": "openid email profile",
  "expires_at": 1715000000
}

The strategy.type field tells you how to apply the credentials. See Authentication Strategies for all strategy types and their credential shapes.

Revoking a connection¶

DELETE /v1/connections/{id} permanently terminates a connection. It:

Attempts an RFC 7009 revocation at the provider, when the provider advertises a revocation endpoint.
Deletes the encrypted credential from the database.
Closes every open agent session bound to the connection.
Moves the connection to the terminal revoked status.

Optional workspace_id and reason may be sent as query parameters or in a JSON body; body values take precedence. When workspace_id is supplied it must match the connection's workspace, otherwise the call returns 404 — a workspace-scoped caller cannot revoke another workspace's connection. reason is capped at 512 characters, and a request body that cannot be read is rejected with 400 invalid_body rather than being treated as an unscoped revocation.

{
  "connection_id": "b1f0…",
  "provider_name": "google",
  "status": "revoked",
  "revoked_at": "2026-01-01T12:00:00Z",
  "already_revoked": false,
  "token_deleted": true,
  "sessions_closed": 2,
  "provider_revoked": true
}

provider_revoked is not the same as token_deleted

Nexus always destroys its own copy of the credential, so a revoked connection can never be used through Nexus again. Whether the token was also invalidated upstream depends on the provider supporting RFC 7009 and being reachable at the time of the call. If provider_revoked is false, read provider_revocation_error and, for incident response, revoke the grant manually in the provider's console. Static credentials (api_key, basic_auth) have no revocation endpoint and must always be rotated at the provider.

Revocation is idempotent: revoking an already-revoked connection returns 200 with already_revoked: true. The retry reports the original revocation — the stored revoked_at and the upstream outcome that was recorded at the time — rather than a fresh timestamp, so a client retrying after a timeout confirms what actually happened instead of reading a plausible-looking fiction.

After revocation, GET /v1/token/{id} and POST /v1/refresh/{id} return 410 Gone with code connection_revoked. The status is terminal: a revoked connection is never reactivated, so clients must stop retrying and start a new connection flow. A credential write that was already in flight when the revocation committed — a refresh, an OAuth exchange, a static capture — is rejected with the same 410, so it cannot recreate the credential that was just destroyed.

Broker API¶

Internal surface. Called by the Gateway and administrative tooling (nexus-cli). Do not expose the Broker to agents or untrusted networks.

The Broker's OpenAPI spec is at nexus-broker/openapi.yaml. It evolves between minor versions — fields and endpoints may change.

Agent registry endpoints (admin)¶

Method	Path	Description
`POST`	`/admin/v1/agents`	Register an agent with its allowed scopes
`GET`	`/admin/v1/agents`	List all registered agents
`GET`	`/admin/v1/agents/{id}`	Get a specific agent
`PATCH`	`/admin/v1/agents/{id}`	Update agent allowed scopes
`DELETE`	`/admin/v1/agents/{id}`	Deregister an agent

Audit¶

Method	Path	Description
`GET`	`/audit`	Query audit log events

All Broker API calls require the X-API-Key header. See the Audit Log guide for query parameters and response schema.