API keys let your code and CI ask questions and read results. For AI assistants like Claude or ChatGPT, connect with MCP and OAuth instead: it needs no key.

Making a key

  1. Go to Developers in the portal and choose Create key.
  2. Name it after where it will be used, for example "CI" or "pricing bot".
  3. Choose its scopes and a daily spend cap.
  4. Confirm it's you. The key starts fh_live_ and is shown once: copy it into your secret store straight away.

We store only a hash of the key, so we can't show it again. If you lose it, rotate it.

Scopes

  • questions:read: results and lists.
  • questions:write: estimate, ask, cancel, share, uploads.
  • templates:read: fixed-price templates.
  • account:read: balance and ledger.
  • webhooks:read: see webhook endpoints and their deliveries.
  • webhooks:write: add, change, rotate, test, replay and remove webhook endpoints.
  • apps:read: see the Slack workspaces 50heads is added to, with each one's daily cap.
  • apps:write: change a Slack workspace's daily cap, or remove it. See Use 50heads in Slack.
  • events:read: read the event stream, for warehouse export and tools such as Airbyte (being introduced gradually).

For organisation admins, where your organisation has service accounts (being introduced gradually):

  • organization:read: see the organisation, its domains, sign-in rules, single sign-on, SCIM and service accounts.
  • organization:write: change domains, sign-in rules and SCIM settings.
  • members:read: see where a member of the organisation is signed in.
  • members:write: sign a member out everywhere.
  • audit:read: read and export the audit log.

Make the key while the organisation's team is in use. The organisation scopes work only while you're an admin of the organisation: if you stop being one, the key loses them at once. Some acts always need you, signed in, whatever the key's scopes: the single sign-on connection and making it required, break-glass owners, SCIM tokens, how long audit events are kept, legal holds, handing over a team and service accounts. For an agent that should keep working when people leave, use a service account instead of a key.

Give each key only what it needs. The webhook, apps and organisation scopes are never ticked for you. See Webhooks.

Changing a key

Choose Scopes and caps on a key in Developers to rename it, change its scopes, its daily cap, its per-question cap or the addresses it may be used from. Taking a scope away, renaming and changing a cap take effect at once. Adding a scope asks you to confirm it's you first, as making a key does. If you use two-step sign-in, confirm with your authenticator app, a passkey or a recovery code.

Keys on a team

A key made while a team is in use spends the team's credits. The team's owner and admins can see it, change its caps and revoke it. See Your team.

Rotating and revoking

Rotate makes a new secret for the same key and settings. The old secret keeps working for 24 hours, so you can update your scripts, then stops. Revoke stops the key for good, within a second.

Old keys

Keys made before scopes existed can only ask, read results, use templates and see your balance, and they have no daily cap. You can't make new ones. Any you still have are listed under Legacy keys in Developers, where you can revoke them. We will retire them after 90 days' notice by email. Make a new key with scopes and a cap, move your code to it, then revoke the old one.

Keep keys secret

Keys are for servers. We refuse requests that use a key from a web browser, so a key isn't exposed in a web page. Never commit keys to a repository.

See the developer docs for authentication, errors and rate limits.