Authentication

Every request to the ThirdSectorBee API requires two things: a bearer token and a tenant ID. This page explains how to get both.

Getting your credentials

Personal Access Token

Go to Account Settings → API Access → Generate token.

Use the token as your bearer token on every request:

Authorization: Bearer <your-pat>

Personal Access Tokens are tied to your user account and best suited for small projects or personal scripts. If you’re building an integration that will run as a production service or on behalf of multiple users, use OAuth instead.

OAuth client application

curl https://api.thirdsectorbee.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$TSB_CLIENT_ID \
  -d client_secret=$TSB_CLIENT_SECRET

OAuth tokens expire and must be refreshed. OAuth is the right choice for server-to-server integrations and any product you ship to end users.

Sending credentials on every request

All API requests require both headers:

Authorization: Bearer <token>
X-Tenant-Id: <tenant-id>

Your tenant ID is the identifier for your organisation in ThirdSectorBee. You can find it in Account Settings.

curl https://api.thirdsectorbee.com/programmes \
  -H "Authorization: Bearer $TSB_TOKEN" \
  -H "X-Tenant-Id: $TSB_TENANT_ID"

Your token carries information about which organisations you have access to. If the X-Tenant-Id header names an organisation your account is not a member of, the request is rejected with 403 Forbidden. A valid token alone never grants access to an organisation you don’t belong to.

Status codes

Code	Meaning
`401 Unauthorized`	Your token is missing, expired, or invalid.
`403 Forbidden`	Your token is valid but does not grant access to the requested organisation. Check your `X-Tenant-Id` header.

See Quickstart → Handle errors for the full error response format.

Public endpoints

Some endpoints require neither header — for example the Engage /public/* endpoints used by embedded forms on public websites. These are marked as public in their respective API references.