Authentication

The Bindly workspace API accepts two kinds of credentials. Pick the one that fits what you are building:

• A backend, script, or scheduled job: use a workspace API key.
• A CLI or other headless client with a person present: use the device flow.
• A CLI on a machine with a browser: use browser sign-in.
• A client that registers itself, such as an AI tool: use dynamic client registration.

Both kinds resolve to a single workspace, and all data is scoped to that workspace. See Data scoping.

Workspace API keys

A workspace API key is the simplest way to call the API from a server or a script. Keys are prefixed bsk_ and grant full access to your workspace’s API.

Create one in the Bindly app under Agency profile then API keys. Store it as a secret. Send it on every request, either as a bearer token or as an X-API-Key header:

Bearer

curl "https://engine.bindly.insure/org/sessions" \
  -H "Authorization: Bearer bsk_live_xxx"

X-API-Key

curl "https://engine.bindly.insure/org/sessions" \
  -H "X-API-Key: bsk_live_xxx"

Caution

A workspace API key is a long-lived secret with full workspace access. Keep it server-side, never commit it, and rotate it if it leaks. Revoke a key any time under Agency profile then API keys. For interactive or AI clients, prefer the short-lived OAuth token flows below.

OAuth 2.1

For interactive and AI clients, Bindly runs OAuth 2.1. Tokens are short-lived bearer tokens sent in the Authorization header:

Authorization: Bearer <token>

Discovery

The authorization server publishes its metadata at a standard discovery endpoint. Clients should read it rather than hard-coding endpoint paths:

curl "https://engine.bindly.insure/.well-known/oauth-authorization-server"

The document lists the token, authorization, device authorization, and registration endpoints, along with the supported grant types.

Device flow

The Device Authorization Grant (RFC 8628) is the default for the bindly CLI and any headless client. The user approves the sign-in in a browser while the client polls for a token.

1. Request a device code.

   curl -X POST "https://engine.bindly.insure/oauth/device_authorization" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=$BINDLY_CLIENT_ID"

   The response includes a user_code, a verification_uri, a verification_uri_complete, a polling interval, and an expires_in.

2. Send the user to approve.

   Show the verification_uri and user_code, or open the verification_uri_complete for them. They sign in to Bindly and approve the request. The workspace the token is scoped to comes from that authenticated session, never from the client.

3. Poll for the token.

   curl -X POST "https://engine.bindly.insure/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=$BINDLY_CLIENT_ID"

   Poll at the interval the server returned. While the user 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 Bindly, the user approves, and the code is returned to a local http://127.0.0.1 listener and exchanged for a token:

bindly login --browser

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://engine.bindly.insure/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Workspace Tool",
    "redirect_uris": ["http://127.0.0.1:4567/callback"]
  }'

Note

Registration issues public PKCE clients with no client_secret. Always use PKCE, and confirm the requesting client’s destination host on the consent screen before approving.

Using the token

Send the access token, or the workspace API key, on every request:

curl "https://engine.bindly.insure/org/sessions" \
  -H "Authorization: Bearer $BINDLY_TOKEN"

OAuth access tokens are short-lived. When one expires, use the rotating refresh token to get a new pair, or run the sign-in flow again. Workspace API keys do not expire until you revoke them.