Keys and scopes
Key types, the read and write scopes, account allow-lists, rotation and revocation.
Every request to BetterFans Link carries a key. The key decides the workspace, the mode, what the caller can do and which accounts it can see.
Key types
| Starts with | What it is |
|---|---|
bfl_live_ | A live secret key you create in the dashboard. It reads the accounts linked to your workspace. |
bfl_test_ | A test secret key you create in the dashboard. It reads the sandbox creators and never reaches OnlyFans. |
bfl_oauth_ | A key an MCP client received through OAuth. You never handle it; revoke it by revoking the client. |
bfl_dash_ | The dashboard's own key. It never leaves BetterFans Link and is the only key that runs approved actions. |
You only ever create bfl_live_ and bfl_test_ keys. MCP clients that connect with OAuth get their own key, and the dashboard uses its own.
Sending a key
Send the key as a bearer token. The x-api-key header works too, for tools that cannot set Authorization.
curl https://app.betterfans.link/v1/me -H "Authorization: Bearer $BFL_KEY"
curl https://app.betterfans.link/v1/me -H "x-api-key: $BFL_KEY"Who am I returns the workspace, the key's mode, scopes and account list, and its rate limit. Call it first when something looks wrong.
Creating a key
In the dashboard, open Developers, then API keys. Owners, admins and developers can create keys. Choose these settings.
| Setting | Options |
|---|---|
| Name | 1 to 60 characters. It appears in logs and on approvals, so name it after what uses it. |
| Scopes | read, write or both. |
| Accounts | Every account, or only the ones you pick. |
| Expiry | Never, or after 1 to 365 days. |
The full key is shown once, when you create it. After that the dashboard shows only its first 12 and last 4 characters. Store it in a secret manager or an environment variable.
Scopes
| Scope | Allows |
|---|---|
read | Every GET route, and creating hosted links with POST /v1/links. |
write | Creating actions with POST /v1/accounts/{accountId}/actions. Every action still waits for a person to approve it. |
A key without the scope a route needs gets 403 missing_scope. Give a key write only if it asks for writes. A reporting job never needs it.
Account allow-lists
A key set to every account reaches every account linked to the workspace, including accounts linked after the key was made. A key limited to some accounts reaches only those.
For any other account, every route returns 404 account_not_found, exactly as if the account were not linked. List accounts returns the accounts the key can reach. In GET /v1/me, key.accountIds is null for a key set to every account.
Use an allow-list when a key serves one creator, or when you hand a key to someone who works on only some of your accounts.
Changing, rolling and revoking
- Change a key's name, scopes or accounts at any time on its page. The change takes effect within 30 seconds.
- Roll a key to replace its secret. The new key is shown once, and the old one keeps working for the time you choose: it stops now, in 1 hour or in 24 hours. Use the overlap to deploy the new key.
- Revoke a key to stop it for good. Revocation takes effect within 30 seconds.
A request with a revoked or expired key gets 401 revoked_api_key or expired_api_key.
MCP clients
An MCP client that connects with OAuth, such as Claude.ai or ChatGPT, gets a workspace, a mode and scopes from the person who approves it on the consent page. It reaches every account in that workspace. The Developers, then MCP page lists connected clients. Disconnecting one there cuts it off, along with its tokens, within 30 seconds. See MCP.
Roles
People in a workspace have one of four roles. The role decides what they can do in the dashboard, including who can approve writes.
| Role | Can do | Approves writes | Links accounts |
|---|---|---|---|
| Owner | Everything, including deleting the workspace. | Yes | Yes |
| Admin | Everything except deleting the workspace. | Yes | Yes |
| Developer | Keys, webhooks, logs and linking accounts. Cannot approve writes or manage the team. | No | Yes |
| Read only | Can see data, logs and settings. Cannot change anything. | No | No |
Keeping keys safe
- Use keys only on a server. Never put one in a browser, a mobile app or a public repository.
- Use a separate key for each service, so you can revoke one without breaking the others.
- If a key leaks, roll it with the old key set to stop now, then check its requests on the Logs page.
See security.