Skip to content

api.md

Latest commit

 

History

History
100 lines (71 loc) · 3.89 KB

api.md

File metadata and controls

100 lines (71 loc) · 3.89 KB
icon material/code-json

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
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.

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.