Tokens work only in the environment of the client that issued them.
Choose an environment for each stage
Sandbox
Use Sandbox for development, CI, and demos. You can complete authorization and use sample linked accounts with repeatable test data. Sandbox never contacts OnlyFans, so there is no risk of triggering OnlyFans security checks. Sandbox accounts always have Vault+ on. Sandbox accounts are created in the dashboard under your integration’s Sandbox environment. Only members of the integration’s organization who can manage the integration’s credentials can authorize them, and consent offers only that organization’s Sandbox accounts. Someone outside your organization who has the Sandbox client ID cannot authorize. Each Sandbox authorization shares exactly one account: consent lists the accounts by name and lets you pick one. To share another account, run authorization again and pick it; it is added to the same authorization. If a selection is refused, the user returns to your redirect URI witherror=access_denied and an error_description.
You can test reconnects in Sandbox. Expire a Sandbox account in the dashboard and it shows as needs_reconnect. POST /v3/linked-accounts/{id}/reconnect returns a reconnect URL that restores the account without an OnlyFans sign-in and returns to your redirect_uri with state and reconnect=completed, as in Live. The dashboard’s Reconnect also restores it. Either way the account keeps its existing authorizations.
Because the data is mock, Sandbox cannot verify that your integration handles real account states. Use Test for that.
Sample data
Each Sandbox account has its own profile, built from the account’s name and username, and its own sample fans, chats, Vault, mass messages, and stories. Sandbox plays the part of OnlyFans only: it produces the OnlyFans response, and the rest of the request runs exactly as in Live, with the same validation, response shapes, media URLs, and errors. So responses contain the same fields as in Live. Like OnlyFans, the chat list and thread messages identify a fan by ID. An inbox can get the profiles directly: chat lists called withinclude_users=true return each chat’s user and lastMessage.sender with their name, username, and avatar. Otherwise get the fan’s name from GET /v3/access/users/{userId} or POST /v3/access/users/batch. All three always agree. The same fan has the same ID everywhere. Threads mix messages from the creator and the fan, and every message has its own ID. Dates are recent, items are in their normal successful state (media is ready, mass messages are not cancelled), and media, avatars, and covers are placeholder images that load. Placeholders are heavily blurred abstract images, like a locked preview, at the sizes the media reports. Video playback works from the same API origin that served the response, including a local stack.
The sample data for an account stays the same between requests, so tests can rely on it. Dates move with the current time.
Writes are kept for 24 hours
These writes change what later reads return for the same linked account:
Reading, changing, or deleting an item the account does not have (never created, or deleted) returns
404.
Sandbox does not store uploaded files. You can run the whole upload flow (POST /v3/access/uploads/start, PUT each part, finalize) with files up to 1 MiB; the part bytes are discarded. A larger declared size or part body returns 413. Uploaded media, upload references, and http(s) media URLs always show one of a few placeholder images (a video placeholder for video content types), so two uploads can look the same but keep their own media IDs. Media URLs you pass are never fetched. Other writes are validated and answered with sample data, but are not kept.
Kept data is short-lived and capped so it cannot grow without limit:
- Each change is kept for 24 hours after it was last written. After that the account shows its sample data again for that item.
- Each account keeps at most 200 changes of one kind (for example, one chat thread, or Vault lists) and 2,000 in total. When a limit is reached, the least recently written changes are removed first.
- Changes belong to one linked account. Other accounts, and other integrations, never see them.
Realtime in Sandbox
Sandbox accounts send Realtime events the same way Live accounts do, over the Realtime stream and to webhook destinations. They use the Realtime event selection and filters of your Sandbox client, and each event has the same payload as in Live. Events come only from simulated fans and from the platform. Your own API writes do not send events, just as OnlyFans does not echo your own actions. Fans can react to what you do, for example by replying some time after you message them.
Every activity is written to the account before its events are sent, so a read after an event shows what the event reports:
- the message in the thread of the event’s
withUserId(the same fan as the typing event’sidbefore it); isLikedon the liked message;- the profile’s
chatMessagesCount,unreadTips, andnotificationsCount; - the notification in the notifications list;
- the story’s views and likes.
realtime.post.published, because it does not publish scheduled posts. Mass messages have no Realtime event, so none is sent when a scheduled one goes out.
The simulation runs only while something is listening:
- while a Realtime stream is connected;
- for 30 minutes after an API request for the account, when your integration has a verified Sandbox webhook destination that receives Realtime events.
- Replies to your messages come first. A few seconds after you send a fan a message through the API, that fan types and replies, even when the rest of the simulation has used its share of the hour. 60 of the 300 events are kept for these replies.
- Background activity slows down as the hour fills. It starts at about one activity every 4 to 12 seconds, and the gap grows with the share of its 240 events already sent in the last hour, up to 10 minutes. It settles at about 140 to 180 events an hour, so a socket left open for hours keeps getting events and never reaches the limit.
POST /v3/sandbox/events with your access token and x-linked-account-id, as you would an Access request:
{ "deliveries": [{ "type", "eventId" }] }). Each one goes to a connected socket and to your webhook destinations, if there are any. The list is empty when none of the account’s authorizations selects the event. Events you send this way count toward the 300-per-hour limit, and when it is reached the call returns 429 with sandbox_event_limit. They also use up the room kept for replies, so a fan can’t reply until the hour frees up. Without data, the matching simulated activity runs and is written first. With data, that payload is checked against the event’s public schema and sent as given, and nothing is written. For example, { "type": "realtime.chat_message.liked", "data": { "id": 42, "isLiked": true, "withUserId": 7 } } sends a like with its optional chat partner. Simulated likes have none, as in Live. You can send any of these event types:
realtime.chat_typing.updatedrealtime.chat_message.receivedrealtime.inbox_counts.updatedrealtime.chat_message.likedrealtime.chat_message.unlikedrealtime.toasts.receivedrealtime.stories.updatedrealtime.post_fundraising.updatedrealtime.system_message.receivedrealtime.system_messages.updated
- Expire in the dashboard sends
linked_account.expired. - Reconnect, in the dashboard or through the reconnect URL, sends
linked_account.reconnected. - Delete sends
linked_account.disconnected.
Test
Use Test to check your app with real OnlyFans accounts you control. Only accounts designated by the integration owner in the dashboard can be shared. Each day a fixed number of Access operations are allowed; when the quota is used up, calls return429 quota_exhausted with Retry-After set to the seconds until the UTC reset.
Live
Live is for your customers. Requirements:- An active Developer plan on your organization.
- Live approval of your External Integration. Request it from the dashboard once your integration works in Test. Approval reviews your purpose statement, scopes, redirect URIs, and privacy policy.
- HTTPS redirect URIs with domain hostnames. Live consent displays the purpose from the approved integration configuration.
integration_not_approved. Without the plan, they fail with subscription_required. See Errors.
Switching environments in code
The client ID and secret select the environment. Keep one configuration object per environment.Node.js
JSON.stringify([clientId, appUserId]) consistently for authorization and API calls. See token storage.
Store the client ID with each linked account choice too. An account selected in Sandbox must not become the selection for Live. A Sandbox token cannot reach a Live account, and a Live linked account id does not exist in Sandbox.