OAuth#

Use OAuth when a third-party client needs delegated access to a Hightop agent selected by a Hightop user.

Header-key auth is usually simpler for your own backend. OAuth is for integrators, connectors, and external clients.

Discovery#

The authorization server publishes discovery at:

textexample

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

Endpoints#

textexample

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.

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:

textexample

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.

Scopes#

Scope	Capability
`agent:read`	Read balances, activity, operations, and resource lists
`agent:simulate`	Simulate Agent API requests without broadcasting
`agent:payments:write`	Create payments and one-off payment operations
`agent:conversions:write`	Execute conversions from quotes
`agent:withdrawals:write`	Create bank or crypto withdrawal operations
`agent:earn:write`	Deposit, withdraw, move, and claim rewards in earn products
`agent:borrow:write`	Borrow, repay, deleverage, and adjust collateral
`agent:webhooks:manage`	Create, update, delete, rotate, and test webhook endpoints

Route enforcement has two layers:

The token must include the route's required scope.
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.

Flow#

textexample

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:

textexample

POST /oauth/token/revocation

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

Auth Failures#

Invalid or revoked Bearer tokens return 401 invalid_token.

Tokens that are valid but missing the required scope return 403 insufficient_scope and include a WWW-Authenticate header with the required scope.

See Errors.