BetterFans Link API keys and scopes
Key types, the read and write scopes, account allow-lists, rotation and revocation.
Product page: OnlyFans agency API
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, Fansly or Fanvue. |
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://betterfans.link/v1/me -H "Authorization: Bearer $BFL_KEY"
curl https://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.
How to get an OnlyFans, Fansly or Fanvue API key
OnlyFans and Fansly issue no API keys, and Fanvue's own keys belong to Fanvue apps. You create a BetterFans Link key on the dashboard's API keys page: a bfl_test_ key for the sandbox creators, then a bfl_live_ key once a creator links an account.
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. |
| Creators | All creators, including ones linked later, or only the ones you pick. |
| Access | Full access or Read only. A Full access key can also have Writes need approval ticked. See Full access. |
| Expiry | Never, or after 1 to 365 days. |
There is nothing to set up on each creator. The dashboard turns on API writes for the creators a key works for when you create or change it.
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.
Full access
Full access gives a key read and write permission for the creators it works for: every creator linked to its workspace, including creators added later, or only the ones you pick. Its writes skip approval, and a live key also gets Direct access. Test keys still use only the sandbox. Only owners and admins can give a key Full access in live mode; developers can in test mode.
Tick Writes need approval to keep reads and writes but have each write wait in Approvals until someone approves it. Pick Read only for a key that never writes.
To change a key, open it and change its creators or access under Creators and access, then choose Save access. Giving a key Full access asks you to type its name; the secret stays the same. Revoking the key, removing a creator from the workspace, or an unavailable creator connection still prevents requests. A key made before these choices existed shows as Custom access and keeps its settings until someone picks one.
If writes are off for one of a key's creators, for example one linked after the key was made, the key's page says so and turns them on in one click.
Scopes
| Scope | Allows |
|---|---|
read | Every GET route, and creating hosted links with POST /v1/links. |
write | Creating actions with POST /v1/accounts/{accountId}/actions. Each action waits for a person to approve it, unless the key has auto-approve on. |
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.
Picking creators
A key set to all creators reaches every account linked to the workspace, including accounts linked after the key was made. A key limited to some creators 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.
Pick creators when a key serves one creator, or when you hand a key to someone who works on only some of your accounts. This works with every kind of access, Full access included.
Changing, rolling and revoking
- Change a key's name, access or creators 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.
Auto-approve
Auto-approve makes a key's writes run as soon as it asks for them. POST /v1/accounts/{accountId}/actions then answers 200 with the action already executed or failed, instead of 202 with a pending action. The action has autoApproved: true and still shows in Approvals and Logs. No action.pending webhook is sent; action.executed or action.failed is.
- Only a key with the
writescope can have it. MCP clients that sign in with OAuth and the dashboard key cannot. A test key can, and its writes stay simulated. - Full access turns it on. Writes need approval and Read only turn it off. In live mode only owners and admins can change it; developers can in test mode. Every change shows in the audit log.
- Unless the key has Full access to all creators, the account's API writes switch also applies. The dashboard turns it on for a key's creators; with writes off, the key gets
403writes_disabled. - Only an owner or admin can give an auto-approve key more accounts. Removing the
writescope turns auto-approve off. A rolled key keeps it only when an owner or admin rolls it. - Turning auto-approve off takes effect on the next write request.
Direct access
Direct access lets a live key also call the creator API. The creator API sends messages and makes other changes as your linked OnlyFans, Fansly and Fanvue accounts right away, with no approval. Actions you create with POST /v1/accounts/{accountId}/actions follow the key's auto-approve setting, not Direct access.
- Only a live key with the
writescope can have it. Test keys, the dashboard key and the keys of clients that sign in with OAuth cannot. - Full access turns it on for a live key, after an owner or admin types the key's name. Writes need approval and Read only turn it off. Both show in the audit log.
- Unless the key has Full access to all creators, the account's API writes switch also applies. With writes off, any request other than
GETorHEADgets403writes_disabled. Reads still work. - The key reaches the same accounts on the creator API as here. Only an owner or admin can give a key with Direct access more accounts.
- Removing the
writescope turns Direct access off. A rolled key keeps it only when an owner or admin rolls it. - Every request shows in Logs under the key's name.
Send the key as a bearer token or in the x-service-api-key header, never in a URL. The creator API has its own address, not the BetterFans Link API's. Ask us for it when you give a key Full access.
| Route | What it does |
|---|---|
GET /v1/accounts | Lists the OnlyFans accounts the key reaches. |
/v1/access/{accountId}/... | Calls OnlyFans as that account. |
GET /v1/fansly/accounts | Lists the Fansly accounts the key reaches. |
/v1/fansly/access/... | Calls Fansly as the account named in the x-fansly-account-id header. |
/v1/fansly/ws/connect?accountId=... | Opens a WebSocket of that Fansly account's live events. |
GET /v1/fanvue/accounts | Lists the Fanvue accounts the key reaches. |
/v1/fanvue/access/... | Calls Fanvue's API as the account named in the x-fanvue-account-id header. |
GET /v1/accounts and GET /v1/fansly/accounts and GET /v1/fanvue/accounts answer 401 until the key has Direct access, which Full access gives a live key, so either one tells you whether it has taken effect. Each account they list carries writesEnabled, so you can tell which accounts take writes before you send. A test key, or a key with Direct access off, gets 401. A key without read gets 403 missing_scope on GET requests. An account the key cannot reach gets 403 account_not_found.
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 MCP integration 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 | What they do |
|---|---|
| Owner | Everything an admin can do, plus deleting the workspace and adding or removing owners. |
| Admin | Manages the team and settings, removes accounts and approves writes. |
| Developer | Reads fan data and builds with keys, webhooks, connected apps and account links. Approves writes in test mode only. |
| Workspace viewer | Sees accounts, approvals, logs, usage, the team and the audit log. Cannot read fan data or change anything. |
Each role can do everything the role below it can. Test mode only touches sandbox creators, so a developer can also approve test writes there.
| Permission | Owner | Admin | Developer | Workspace viewer |
|---|---|---|---|---|
| See accounts, links, approvals, request logs, usage, keys, webhooks, the team and the audit log | Yes | Yes | Yes | Yes |
| Read fan data: fans, chats, messages, content, revenue detail and event payloads | Yes | Yes | Yes | No |
| Create keys and webhooks, connect apps and link accounts | Yes | Yes | Yes | No |
| Approve or reject writes and turn writes on or off for an account | Yes | Yes | Test mode only | No |
| Rename the workspace, invite and remove teammates, change roles, remove accounts and see invoices | Yes | Yes | No | No |
| Choose the plan, manage payment, delete the workspace and add or remove owners | Yes | No | 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.