> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> Choose Sandbox for sample data, Test for your accounts, or Live for customers.

Each integration has three environments: Sandbox, Test, and Live. Each environment has its own client ID and secret, callback URLs, linked accounts, tokens, webhook destinations, and data. You cannot use these in another environment.

The client ID selects the environment. You do not need a resource or environment parameter.

| | Sandbox | Test | Live |
| - | - | - | - |
| Client ID | `ofext_sandbox_...` | `ofext_test_...` | `ofext_live_...` |
| Data | Mock. No OnlyFans calls are made. Writes are kept for 24 hours. | Real. Only the integration owner's designated test accounts. | Real customer accounts. |
| Who can authorize | Members of the integration's organization who can manage its credentials, for that organization's Sandbox accounts. | Members of your organization using designated test accounts. | Any OFAuth user. |
| Operation limits | Standard rate limits. | Standard rate limits plus a daily operation quota. | Standard rate limits. |
| Redirect URIs | HTTPS, or `http://127.0.0.1` / `http://[::1]` loopback. | Same as Sandbox. | HTTPS with a domain hostname only. |
| Consent purpose | Not required. | Not required. | Resolved from approved app configuration. |
| Approval | None. | None. | Live approval of your integration. |

Tokens work only in the environment of the client that issued them.

## Choose an environment for each stage

![Develop with mock Sandbox accounts, configure Test credentials and authorize designated real accounts, then obtain approval and authorize customer accounts with Live credentials. Credentials, accounts, and tokens do not transfer.](https://mintcdn.com/ofauth/VVqOdSxbrh7mDF0M/images/v3/environments.svg?fit=max\&auto=format\&n=VVqOdSxbrh7mDF0M\&q=85\&s=b8176aa6521109d3a6ee252f270fcdd0)

This is a development sequence. Accounts, tokens, and webhook destinations do not move between these environments. Authorize separately with each environment's client.

## 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 with `error=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 with `include_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:

| Area | Writes | Reads that show them |
| - | - | - |
| Chats | Send, unsend, like and unlike a message; mark all as read; mute, unmute, hide, and delete a chat | Thread messages and the chat list (last message, unread count, muted) |
| Vault | Create, rename, and delete a list; add and remove list media; hide media; finalize an upload with `vaultUpload` | Vault lists, list media, Vault media, single media and list reads |
| Mass messages | Create (now or scheduled), update, delete or cancel; publish a scheduled message | Queue schedules, queued message reads, mass message details, and sent mass messages |
| Stories | Create and delete a story; create, replace, update, and delete a highlight; remove a story from a highlight | Active stories, story archive, highlights list, and highlight reads |

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.

Use this to test read-after-write and optimistic updates. Do not use Sandbox as storage.

### 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.

| Simulated activity | Events |
| - | - |
| A fan types and then sends a message (sometimes with a tip) | `realtime.chat_typing.updated`, `realtime.chat_message.received`, `realtime.inbox_counts.updated` |
| A fan likes or unlikes one of your messages | `realtime.chat_message.liked`, `realtime.chat_message.unliked` |
| Tips, message purchases, new subscribers | `realtime.toasts.received` |
| Story views and likes | `realtime.stories.updated` |
| Fundraising contributions | `realtime.post_fundraising.updated` |
| A system notice | `realtime.system_message.received`, `realtime.system_messages.updated` |

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's `id` before it);
* `isLiked` on the liked message;
* the profile's `chatMessagesCount`, `unreadTips`, and `notificationsCount`;
* the notification in the notifications list;
* the story's views and likes.

Simulated activity counts toward the limits on kept data described above.

Sandbox does not send `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.

Otherwise it stops. Sandbox sends at most 300 events per account in any rolling hour:

* **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.

To send an event now, call `POST /v3/sandbox/events` with your access token and `x-linked-account-id`, as you would an Access request:

```json theme={null}
{ "type": "realtime.chat_message.received" }
```

The response lists the events Realtime delivery accepted (`{ "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.updated`
* `realtime.chat_message.received`
* `realtime.inbox_counts.updated`
* `realtime.chat_message.liked`
* `realtime.chat_message.unliked`
* `realtime.toasts.received`
* `realtime.stories.updated`
* `realtime.post_fundraising.updated`
* `realtime.system_message.received`
* `realtime.system_messages.updated`

Expiring, reconnecting, or deleting a Sandbox account sends the same lifecycle webhooks as in Live:

* **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 return `429 quota_exhausted` with `Retry-After` set to the seconds until the UTC reset.

> [!WARNING]
>
> Avoid repeated logins to real accounts. Too many login attempts can trigger OnlyFans "suspicious activity" detection. Link each test account once and rely on refresh tokens.

## Live

Live is for your customers. Requirements:

1. An active Developer plan on your organization.
2. 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.
3. HTTPS redirect URIs with domain hostnames.
   Live consent displays the purpose from the approved integration configuration.

Until approval, Live calls fail with `integration_not_approved`. Without the plan, they fail with `subscription_required`. See [Errors](https://docs.ofauth.com/v3/api-reference/errors.md).

## Switching environments in code

The client ID and secret select the environment. Keep one configuration object per environment.

```javascript Node.js theme={null}
const environments = {
  sandbox: {
    clientId: process.env.OFAUTH_SANDBOX_CLIENT_ID,
    clientSecret: process.env.OFAUTH_SANDBOX_CLIENT_SECRET,
    redirectUri: "http://127.0.0.1:3000/oauth/ofauth/callback"
  },
  live: {
    clientId: process.env.OFAUTH_LIVE_CLIENT_ID,
    clientSecret: process.env.OFAUTH_LIVE_CLIENT_SECRET,
    redirectUri: "https://developer.example.com/oauth/ofauth/callback"
  }
}
```

Keep token storage separate for each client. Your auth framework or application owns token storage. Use `JSON.stringify([clientId, appUserId])` consistently for authorization and API calls. See [token storage](https://docs.ofauth.com/v3/sdk/typescript.md#store-customer-tokens).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.