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

Two scopes gate what a token can do:

Scope	Grants
broker_mcp	Read access: submissions, markets, the thread, programs and application schemas, policies, payments, appetite.
broker_submit	Write access: send a risk (intake, submissions), upload documents, reply on the thread, answer outstanding asks, withdraw, release a held submission, work carrier applications, and request binds.

A token’s scope is always tied to the authenticated brokerage, never to the client. Read more about scope enforcement in Conventions.

Access

Every brokerage on Hedge has API access. Nothing is switched on by Hedge per brokerage:

• API keys are self-serve under Settings → API keys in the broker portal. Any broker user can create a read-only key; a key that carries broker_submit is created by a brokerage admin.
• The CLI signs a broker in with the device or browser flow and gets the scopes the broker approves.
• The MCP connector uses the same OAuth server: the broker approves the connection once, and the consent screen shows whether the tool can write.

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

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.

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.

1. Request a device code.

   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, a verification_uri (the portal’s /device page), a verification_uri_complete, a polling interval, and an expires_in.

2. Send the broker to approve.

   Show the broker the verification_uri and user_code, or open the verification_uri_complete for 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.

3. Poll for the token.

   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 an access_token and a refresh_token.

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 --browser

The 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

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.

Note

Because registration issues public clients, always use PKCE and confirm the requesting client’s destination host on the consent screen before approving.

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. 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 write made with one names the producing broker with producer_email, an active portal user of your brokerage: POST /broker/intake and POST /broker/submissions (producer_email in the form or body), thread replies, outstanding-requirement answers, withdrawals, bind requests, contingency uploads and bind submits. The write is attributed to that broker in the portal and on the clearance email. 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. They are also refused by the MCP write tools; the MCP connector uses the interactive flows. 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

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; write endpoints require broker_submit.