Authentication
The Hedge broker API uses OAuth 2.1. Every request carries a short-lived
bearer token in the Authorization header:
Authorization: Bearer <token>Requests never authenticate with a static key: tokens are short-lived,
audience-bound bearer JWTs, and refresh tokens rotate on every use. Machine
credentials exist (a client_id/client_secret pair, created self-serve in
the broker portal), but they are only ever exchanged for a short-lived token,
never sent on API requests. How you obtain a token depends on what you are
building:
- A CLI or other headless client: use the device flow.
- A CLI on a machine with a browser: use browser sign-in.
- A first-party or third-party client that registers itself: use dynamic client registration.
- A server-to-server integration: use client credentials.
Scopes
Section titled “Scopes”Two scopes gate what a token can do:
| Scope | Grants |
|---|---|
broker_mcp |
Read: appetite, requirements, your files and their market states, quotes and documents, events, policies, payments. |
broker_submit |
Submit: create and intake, answer, quote, bind link, upload documents, withdraw. |
A token’s scope is always tied to the authenticated brokerage, never to the client. Read more about scope enforcement in Conventions.
Read is self-serve; submit is turned on by Hedge
Section titled “Read is self-serve; submit is turned on by Hedge”- Read (
broker_mcp) is self-serve. Any broker user can create a read key under Settings → API keys in the broker portal, or sign in with the CLI or the MCP connector. Read covers appetite and requirements, so an agent can assemble a complete submission even without submit access. - Submit (
broker_submit) is turned on per brokerage by Hedge. A brokerage admin asks for it in the portal (Settings → API keys → Request submit access). Until it is on, every token is issued withoutbroker_submit, whatever scope you ask for; the token response’sscopesays what was granted. Submit keys are created by a brokerage admin once submit access is on. - The CLI and the MCP connector use the same OAuth server: the broker approves the connection once, and the consent screen shows whether the tool can write.
A submit call made with a read-only token returns 403. Don’t retry it: it
fails the same way until Hedge turns submit access on.
Brokerage admins keep control of writes on their side: Settings → Connected apps lists every connected tool, revokes any of them, and holds the Agent write access switch that decides whether connected AI tools may write. Machine credentials are revoked under Settings → API keys.
Discovery
Section titled “Discovery”The authorization server publishes its metadata at a standard discovery endpoint. Clients should read it rather than hard-coding endpoint paths:
curl "https://api.hedgespecialty.com/api/v1/oauth/.well-known/oauth-authorization-server"The document lists the token, authorization, device authorization, and
registration endpoints, along with supported grant types and scopes. The
sandbox publishes its own at
https://sandbox-api.hedgespecialty.com/api/v1/oauth/.well-known/oauth-authorization-server;
its tokens and keys work only there.
Device flow
Section titled “Device flow”The Device Authorization Grant (RFC 8628)
is the default for the hedge CLI and any headless client. The broker approves
the sign-in in the browser while the client polls for a token.
-
Request a device code.
Terminal window curl -X POST "https://api.hedgespecialty.com/api/v1/oauth/device_authorization" \-H "Content-Type: application/x-www-form-urlencoded" \-d "client_id=$HEDGE_CLIENT_ID" \-d "scope=broker_submit"The response includes a
user_code, averification_uri(the portal’s/devicepage), averification_uri_complete, a pollinginterval, and anexpires_in. -
Send the broker to approve.
Show the broker the
verification_urianduser_code, or open theverification_uri_completefor them. They sign in to the broker portal and approve the request. The brokerage the token is scoped to comes from that authenticated session, never from the client. -
Poll for the token.
Terminal window curl -X POST "https://api.hedgespecialty.com/api/v1/oauth/token" \-H "Content-Type: application/x-www-form-urlencoded" \-d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \-d "device_code=$DEVICE_CODE" \-d "client_id=$HEDGE_CLIENT_ID"Poll at the interval the server returned. While the broker has not yet approved, the endpoint returns
authorization_pending. Once approved, it returns anaccess_tokenand arefresh_token.
Browser sign-in with PKCE
Section titled “Browser sign-in with PKCE”On a machine with a browser, the CLI can run the Authorization Code flow with
PKCE over a loopback redirect (RFC 8252).
This opens the portal, the broker approves, and the code is returned to a local
http://127.0.0.1 listener and exchanged for a token.
hedge login --browserThe same brokerage-scoping rule applies: the principal comes from the authenticated portal session, and the scope is capped by the brokerage’s programmatic-access controls.
Dynamic client registration
Section titled “Dynamic client registration”Clients can register themselves with Dynamic Client Registration
(RFC 7591). This is how AI tools and
other clients obtain a client_id without a manual setup step.
curl -X POST "https://api.hedgespecialty.com/api/v1/oauth/register" \ -H "Content-Type: application/json" \ -d '{ "client_name": "My Broker Tool", "redirect_uris": ["http://127.0.0.1:4567/callback"] }'The endpoint is public by design and rate-limited per IP. It issues stateless
public PKCE client ids that encode the registered redirect_uris. There is no
client store and no client_secret.
Client credentials
Section titled “Client credentials”Server-to-server integrations that act without an interactive broker use the
Client Credentials grant with a machine credential: a client_id (bac_...)
and client_secret (bas_...) pair.
Any broker user can create a read-only key under Settings → API keys in
the broker portal; keys that carry broker_submit require a brokerage
admin and submit access on the brokerage. The secret is shown exactly once, at creation; store it in a secret
manager. Each brokerage can hold up to 10 active keys; revoking a key frees a
slot and blocks new tokens immediately. The key’s scopes are a ceiling for the
tokens minted from it.
Exchange the credentials for a token:
curl -X POST "https://api.hedgespecialty.com/api/v1/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=$HEDGE_CLIENT_ID" \ -d "client_secret=$HEDGE_CLIENT_SECRET" \ -d "scope=broker_mcp"Machine tokens carry no broker identity, so every submit call made with one
names the producing broker with producer_email, an active portal user of your
brokerage: create and intake (producer_email in the body or form), answers,
quote requests, bind links, uploads and withdrawals. The file and the action
are attributed to that broker. A missing or unknown producer_email is a
422.
Machine credentials cannot manage other machine credentials or webhook
endpoints; both live in the portal only, so a leaked key can never mint a
successor or redirect your event stream. A machine token also works on the
MCP connector, with producer_email on every write, for agents that
run without a person signing in. OAuth grants for interactive apps (Claude,
Cursor, Codex) are managed under Settings → Connected apps.
The hedge CLI wraps this grant: hedge login --client-id bac_... --client-secret bas_...
(or HEDGE_CLIENT_SECRET in the environment) caches the token with its expiry
and renews it by re-exchange, so scripts never handle tokens directly.
Using the token
Section titled “Using the token”Send the access token on every request:
curl "https://api.hedgespecialty.com/api/v1/broker/me" \ -H "Authorization: Bearer $HEDGE_TOKEN"Tokens are short-lived. When one expires, use the rotating refresh token to get
a new pair (per-user flows), or exchange the client credentials again (machine
credentials issue no refresh token). Read endpoints accept a token with
broker_mcp; submit endpoints require broker_submit.
Send a Hedge-Client: <name>/<version> header with your requests so Hedge can
tell your integration apart in its logs.