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:

textexample

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

For most mutating requests, also send:

textexample

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:

textexample

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.

Which Auth Should I Use?#

Caller	Recommended auth	Why
Your backend service calling for your own agents	Header-key auth	Simple server-to-server integration with a key you control
First-party operational workflow inside your stack	Header-key auth	Best fit when no external user consent flow is needed
Third-party client acting after user approval	OAuth Bearer auth	User grants specific scopes to a registered client
MCP client such as Claude Desktop	OAuth Bearer auth	The connector flow obtains a token bound to `/mcp`

Auth Errors#

Authentication errors use the standard error envelope.

error responseapplication/json

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

Header-key auth error codes:

Code	When it is returned
`authentication_failed`	Missing credentials, unknown agent id, API-key mismatch, missing owner, or soft-deleted owner
`agent_disabled`	The API key matched, but the agent is disabled
`agent_not_yet_active`	The API key matched, but the activation window has not started
`agent_expired`	The API key matched, but the activation window has expired

OAuth adds invalid_token and insufficient_scope. See Errors and OAuth.

Two-Layer Authorization#

OAuth scope is only the outer layer. For Bearer-authenticated requests:

The token must include the route's required OAuth scope.
The underlying Hightop agent must still have the relevant capability, permission, asset, destination, and limit allowance.

A token with agent:withdrawals:write cannot withdraw if the selected agent is not allowed to withdraw.