Authentication

Last updated: September 30, 2026

Every BrokerBot API request authenticates with a team API key.

API keys

Send the key as a bearer token:

curl https://api.brokerbot.ai/v1/teams/members \
  -H "Authorization: Bearer $BROKERBOT_API_KEY"

Create a key

  1. Sign in to BrokerBot as a team owner.
  2. Open your team’s Settings → API.
  3. Under API Tokens, generate a token and copy it. It’s only shown once.

Keys last 90 days. Create the replacement before the old one expires, then revoke the old one from the same page.

A key always belongs to your top-level team (your brokerage), even if you create it while viewing a sub-team.

Keep keys secret

  • Keep keys on your server. A key can read your knowledge base, list and change your team’s members, and sign members in to the widget. Never put it in browser code, a mobile app, or a public repository.
  • Store it as a secret, for example in an environment variable such as BROKERBOT_API_KEY.
  • If a key leaks, revoke it under Settings → API and create a new one.

Team scope

A key can only reach its own team and that team’s sub-teams (offices, groups, and so on). Where an endpoint takes a team, it must be inside that tree. Anything outside it returns 404, the same as a team that doesn’t exist, so a key can’t be used to discover other teams.

Nothing in a request can widen that scope. The team always comes from the key.

Base URLs

Base URL Used for
https://api.brokerbot.ai/v1 Team, member, group, and knowledge endpoints.
https://api.brokerbot.ai/auth Widget SSO tokens.

Requests and responses are JSON. Send Content-Type: application/json with every request that has a body.

Authentication errors

Status Body Meaning
401 {"error":"Missing API key"} No Authorization header.
401 {"error":"Invalid API key"} The key is wrong, revoked, or expired.
401 {"error":"API key is not associated with a team"} The key exists but isn’t tied to a team. Create a new key.

See Errors for everything else.