Authentication#

Agent API v1 supports two authentication paths:

• Header-key auth for first-party and backend callers that already hold an agent API key.
• OAuth Bearer auth for third-party clients that receive delegated access from a Hightop user.

Both paths resolve to one Hightop agent and one wallet. The underlying agent capability still controls what can execute.

Header-Key Auth#

Send both headers:

x-agent-id: <agent uuid>
x-api-key: <agent api key>

For most mutating requests, also send:

Idempotency-Key: <unique key for this logical mutation>

API keys are shown once when generated or rotated. Store them in your backend secret manager and rotate if exposed.

OAuth Bearer Auth#

Third-party clients authenticate with an OAuth access token:

Authorization: Bearer <jwt>

For most mutating requests, also send Idempotency-Key.

OAuth tokens are audience-bound. A token issued for https://api.hightop.com/v1/agent cannot be used at https://api.hightop.com/mcp, and vice versa.

OAuth Discovery#

The authorization server publishes discovery at:

GET https://api.hightop.com/.well-known/oauth-authorization-server
GET https://api.hightop.com/.well-known/openid-configuration
GET https://api.hightop.com/.well-known/oauth-protected-resource/v1/agent
GET https://api.hightop.com/.well-known/oauth-protected-resource/mcp

OAuth Endpoints#

POST https://api.hightop.com/oauth/reg
GET  https://api.hightop.com/oauth/auth
POST https://api.hightop.com/oauth/token
POST https://api.hightop.com/oauth/token/revocation
GET  https://api.hightop.com/oauth/jwks

Dynamic client registration is open with rate limits. Verified partners can be pre-registered out of band.

OAuth Authorization Requirements#

OAuth uses Authorization Code + PKCE.

• code_challenge_method=S256 is required.
• plain PKCE is rejected.
• resource is required.
• redirect_uri must exactly match a registered redirect URI.
• Tokens are audience-bound to the requested resource.
• state should be unique, unguessable, tied to the user's session, and verified on return.

Supported resources:

https://api.hightop.com/v1/agent
https://api.hightop.com/mcp

A token issued for /v1/agent cannot be used at /mcp. A token issued for /mcp cannot be used at /v1/agent.

OAuth Scopes#

There is no separate mcp scope. MCP access is controlled by resource binding (a token issued for the ${issuer}/mcp resource) plus these same per-route agent:* scopes. MCP read tools require agent:read, and each mutating tool requires its route's write scope.

Route enforcement has two layers:

1. The token must include the route's required scope.
2. The underlying Hightop agent must have the relevant capability and policy allowance.

For example, a token with agent:withdrawals:write still cannot withdraw if the selected agent itself is not allowed to withdraw.

OAuth Flow#

OAuth client
  |
  | 1. GET /oauth/auth?client_id=...&scope=...&resource=...
  |    &code_challenge=...&code_challenge_method=S256&redirect_uri=...
  v
Hightop authorization server
  |
  | validates client, redirect URI, scope, PKCE, and resource
  | redirects to /connect/<uid> when login or consent is needed
  v
Hightop consent UI
  |
  | user enters email
  | user enters OTP
  | user picks a Hightop agent
  | user approves scopes
  v
OAuth client redirect URI
  |
  | receives authorization code
  | POST /oauth/token with code_verifier and resource
  v
OAuth client
  |
  | receives audience-bound access token and refresh token
  v
Resource server
  |
  | Authorization: Bearer <jwt>
  | verifies signature, audience, expiry, grant status, and scopes

Refresh and Revocation#

Refresh tokens rotate on every use. Replay of a consumed refresh token revokes the entire grant.

Clients can revoke their own tokens:

POST /oauth/token/revocation

End-user revocation from a Connected Applications screen is a planned follow-up unless Hightop source confirms it has shipped.

Which Auth Should I Use?#

Auth Errors#

Authentication errors use the standard error envelope.

{
  "ok": false,
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed."
  }
}

Header-key auth error codes:

OAuth adds invalid_token and insufficient_scope. See Errors and OAuth scopes.