Use OAuth#

Use this when a third-party client needs delegated access to a Hightop agent.

Prerequisites#

A registered OAuth client.
Exact redirect URIs configured for that client.
PKCE S256 support.
A selected resource: https://api.hightop.com/v1/agent or https://api.hightop.com/mcp.

Start Authorization#

Redirect the user's browser to:

textexample

https://api.hightop.com/oauth/auth?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&scope=agent:read%20agent:payments:write&resource=https%3A%2F%2Fapi.hightop.com%2Fv1%2Fagent&code_challenge=<challenge>&code_challenge_method=S256&state=<state>

Use a unique, unguessable state value tied to the user's session and verify it when the user returns to your redirect URI.

The user lands on /connect/<uid>, enters email, enters OTP, picks a Hightop agent, approves scopes, and returns to your redirect_uri with an authorization code.

Exchange the Code#

curlrequest

curl -sS https://api.hightop.com/oauth/token \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=$OAUTH_CLIENT_ID" \
  -d "code=$AUTHORIZATION_CODE" \
  -d "redirect_uri=$REDIRECT_URI" \
  -d "code_verifier=$CODE_VERIFIER" \
  -d "resource=https://api.hightop.com/v1/agent"

Use the returned access token:

curlrequest

curl -sS https://api.hightop.com/v1/agent/self \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Refresh and Revoke#

Refresh tokens rotate on use. Reusing an old refresh token revokes the grant.

curlrequest

curl -sS https://api.hightop.com/oauth/token \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=$OAUTH_CLIENT_ID" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "resource=https://api.hightop.com/v1/agent"

Client revocation:

curlrequest

curl -sS https://api.hightop.com/oauth/token/revocation \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "client_id=$OAUTH_CLIENT_ID" \
  -d "token=$TOKEN"

Likely errors: invalid_token, insufficient_scope, invalid redirect URI, missing resource, invalid PKCE verifier.