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

# Connect OnlyFans account (/introduction/guides/connect-onlyfans-account)

import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

## Why do you need to connect your OnlyFans account?

If you want to use our API to interact with OnlyFans API endpoints like:

* Reading chats
* Sending messages to fans
* Getting statistics
* Getting fans
* Following / unfollowing users
* Getting webhook notifications
* ... basically anything that requires you to be logged in to your OnlyFans account.

Then, you need to connect your OnlyFans account to our API.

You can connect your OnlyFans account in five ways:

1. Using our automated login flow (recommended for most users)
2. Using our **Auth+** iPhone app (recommended when 2FA tokens aren't available to you, or when Face ID is enabled)
3. Add "Login with OnlyFans" to your app
4. Connect using API (programmatic flow)
5. By providing cURL request

<Callout>
  **Which option should you pick?**
  If you (the OFAPI user — e.g. an agency) have easy access to the OnlyFans account's credentials and 2FA tokens, use **Option 1** (automated login flow).
  If you don't have direct access to the creator's 2FA tokens, or the creator's OnlyFans account has **Face ID verification** enabled, use **Option 2** (Auth+ app) — the creator completes sign-in and 2FA on their own iPhone.
</Callout>

<Accordions type="single">
  <Accordion title="Decision flowchart — which option should I pick?">
    <Mermaid
      chart="flowchart TD
    Start([Which auth option should I use?]) --> Q1{Creator has 2FA or<br/>Face Authentication enabled?}
    Q1 -->|No| A1[Dashboard or API]
    Q1 -->|SMS / Authenticator OTP| Q2{Do you have easy access<br/>to these codes?}
    Q1 -->|Face Authentication| Q3{Which Face Authentication<br/>version?}
    Q2 -->|Yes| A2[Dashboard or API]
    Q2 -->|No| A3[Auth+ app]
    Q3 -->|v1| A4[Dashboard, API,<br/>or Auth+ app]
    Q3 -->|v2 — Dashboard/API sessions fail| A5[Auth+ app required]"
    />
  </Accordion>
</Accordions>

### Option 1: Using our automated login flow

This is the recommended flow when you already have the OnlyFans credentials and can enter the 2FA code on behalf of the creator.
Our system can bypass captcha and if you've setup 2FA, you'll be able to enter the 2FA code directly inside our interface while we sign in your profile.

<Callout>
  Your credentials are securely stored in our database and are never shared with
  anyone (not even our engineers can see your credentials).
</Callout>

Steps to connect your OnlyFans account:

1. Go to the [OnlyFans API Console -> Accounts](https://app.onlyfansapi.com/accounts)
2. Click on the **+ Connect Account** button
3. Enter name of the account (this will be used for your reference)
4. Enter your OnlyFans email and password
5. Choose Proxy Country — currently **US** and **UK** are available (we will automatically assign a dedicated mobile IP address for this account), or enter your own proxy details

<Callout type="warn">
  Other proxy countries (DE, FR, IT) have been temporarily removed due to OnlyFans restrictions.
</Callout>

6. Click on the **Add** button
7. Your account will start connecting and you'll see the live progress of the login process.
8. **If you've 2FA enabled on your OnlyFans account**, you'll be asked to enter the 2FA code.
   <img alt="OnlyFans API Console - Connect Account - Enter 2FA code" src={__img0} placeholder="blur" />
9. Done! ✅ You're now able to see the account details and start using your account with our API.

### Option 2: Using our Auth+ iPhone app

<Callout>
  **When to use Auth+:** pick this option only if you (the OFAPI user) don't have easy access to the OnlyFans account's 2FA tokens, or if the creator's OnlyFans account has **Face ID verification** enabled. Otherwise, Option 1 is simpler.
</Callout>

<Callout title="📱 Install the Auth+ app first">
  Before starting a session, the creator should install the **FansAPI Auth+** app on their iPhone via TestFlight:
  [**app.onlyfansapi.com/auth-plus-app**](https://app.onlyfansapi.com/auth-plus-app)

  If they don't already have TestFlight, install it from the App Store first: [**Get TestFlight**](https://itunes.apple.com/us/app/testflight/id899247664?mt=8). The phone-only video below also walks through this.
</Callout>

Auth+ is our iPhone app that lets creators sign in to their OnlyFans account directly from their device. It handles every 2FA method OnlyFans supports — App/SMS OTP as well as Face ID verification — without the creator leaving their phone.

You can start an Auth+ session in two ways: from the [OnlyFans API Console](https://app.onlyfansapi.com/accounts) (creator scans a QR code), or programmatically via the API (creator pastes an auth code).

#### Video guides

Follow one of the two walkthroughs below depending on your setup.

**Desktop + phone flow**

<iframe width="100%" height="400px" src="https://www.youtube.com/embed/M8t57Ck9SuU" title="Auth+ — desktop + phone walkthrough" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen className="rounded-md" />

**Phone-only flow (includes TestFlight install)**

<iframe width="100%" height="400px" src="https://www.youtube.com/embed/4eDh_qAFYMA" title="Auth+ — phone-only walkthrough" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen className="rounded-md" />

#### Step 1a — Start the session from the Dashboard

1. Go to the [OnlyFans API Console -> Accounts](https://app.onlyfansapi.com/accounts)
2. Click on the **+ Connect Account** button
3. Enter the name of the account (this will be used for your reference)
4. Click on **Auth+**
5. Click on the **Add** button

You'll be shown a QR code and an auth code — hand either to the creator for the next step.

#### Step 1b — Or start the session via the API

Call [`POST /authenticate`](/api-reference/connect-onlyfans-account/start-authentication) with `auth_type` set to `mobile_app` and a `display_name` for the account:

```bash
curl --request POST \
  --url 'https://app.onlyfansapi.com/api/authenticate' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "auth_type": "mobile_app",
    "display_name": "My Application / Model: John Doe"
  }'
```

Example response:

```json
{
  "attempt_id": "auth_abc123",
  "message": "Authentication process started. Query the polling_url to check the progress.",
  "polling_url": "https://app.onlyfansapi.com/api/authenticate/auth_abc123",
  "mobile_auth_session_deeplink": "fansapiauth://auth/fansapi_auth_abc123"
}
```

The `mobile_auth_session_deeplink` opens the Auth+ app directly on the creator's iPhone with the session pre-filled. You can also hand them the auth code (`fansapi_auth_abc123`) to paste manually into the app.

#### Step 2 — Complete the sign-in on the creator's iPhone

These steps are the same whether the session was started from the Dashboard or the API.

1. Install **TestFlight** from the App Store
2. Install the **FansAPI Auth+** app via TestFlight: [app.onlyfansapi.com/auth-plus-app](https://app.onlyfansapi.com/auth-plus-app)
3. Open Auth+ and either **scan the QR code** (Dashboard flow) or **paste the auth code** (Dashboard or API flow)
4. Sign in with the OnlyFans email and password
5. Complete any 2FA step (App/SMS OTP or Face Authentication) directly inside the app

Done! ✅ The account is now connected and ready to use with our API.

### Option 3: Add "Login with OnlyFans" to your app

If you want to embed a "Connect with OnlyFans" flow directly in your app UI, use the official auth package.

#### 1) Install package

```bash
npm install @onlyfansapi/auth
```

#### 2) Create a client session token

Create a client session token (`ofapi_cs_...`) from your backend:

`POST /client-sessions`

```bash
curl --request POST \
  --url 'https://app.onlyfansapi.com/api/client-sessions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "My Application / Model: John Doe",
    "client_reference_id": "my-internal-id-123",
    "proxy_country": "us"
  }'
```

#### 3) Start authentication in your frontend

```ts
import { startOnlyFansAuthentication } from "@onlyfansapi/auth";

startOnlyFansAuthentication("ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", {
  onSuccess: (data) => {
    // data.accountId
    // data.username
    // data.response (full response)
    console.log("Connected:", data);
  },
  onError: (error) => {
    // error.message
    // error.code (if available)
    // error.details (if available)
    console.error("Authentication failed:", error);
  },
});
```

<Callout>
  This package handles the OTP / selfie authentication UI flow for you in an embedded modal.
</Callout>

<Callout>
  For the full authentication API and package reference, see: [`/auth`](/auth).
</Callout>

### Option 4: Connect using API (programmatic flow)

Use this flow if you want to connect accounts from your backend or app UI instead of the dashboard.

<Callout>
  Base URL for examples below: <code>[https://app.onlyfansapi.com/api](https://app.onlyfansapi.com/api)</code>
</Callout>

#### 1) Start authentication

`POST /authenticate`

```bash
curl --request POST \
  --url 'https://app.onlyfansapi.com/api/authenticate' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "model@example.com",
    "password": "super-secret-password",
    "proxyCountry": "us"
  }'
```

Example response:

```json
{
  "attempt_id": "auth_xxxxxxxxxxxxx",
  "message": "Authentication process started. Query the polling_url to check the progress.",
  "polling_url": "https://app.onlyfansapi.com/api/authenticate/auth_xxxxxxxxxxxxx"
}
```

#### 2) Poll status until completion or 2FA required

`GET /authenticate/{attempt_id}`

```bash
curl --request GET \
  --url 'https://app.onlyfansapi.com/api/authenticate/auth_xxxxxxxxxxxxx' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

Important fields:

* `state`
* `progress`
* `lastAttempt.success`
* `lastAttempt.needs_otp`
* `lastAttempt.needs_face_otp`
* `lastAttempt.face_otp_verification_url`
* `lastAttempt.error_message`
* `lastAttempt.error_code`

When `lastAttempt.needs_face_otp` is `true`, use `lastAttempt.face_otp_verification_url`.
That URL is the OnlyFans selfie verification page that the creator must open and complete.

#### 3) Submit 2FA code (SMS or OTP app)

`PUT /authenticate/{attempt_id}`

```bash
curl --request PUT \
  --url 'https://app.onlyfansapi.com/api/authenticate/auth_xxxxxxxxxxxxx' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "123456"
  }'
```

If selfie verification is required, submit:

```json
{
  "selfie_verification_completed": true
}
```

<Callout>
  For the standard (v1) selfie verification, no external mobile app is required. The creator only needs to open
  the <code>face\_otp\_verification\_url</code> link in a regular browser on their phone or desktop
  and complete the verification steps there. Alternatively, they can complete it through our [**Auth+ app**](#option-2-using-our-auth-iphone-app).
</Callout>

<Callout type="warn" title="v2 Face Authentication requires Auth+">
  If the creator's OnlyFans account has OnlyFans' **v2 Face Authentication** system enabled, the Dashboard and API flows (without Auth+) **CANNOT** complete sign-in.
  You **MUST** use our [**Auth+ iPhone app**](#option-2-using-our-auth-iphone-app) — it's the only flow that supports v2 Face Authentication.
</Callout>

#### 4) Optional: send OTP verification email to creator

`POST /authenticate/{attempt_id}/send-email-to-creator`

```bash
curl --request POST \
  --url 'https://app.onlyfansapi.com/api/authenticate/auth_xxxxxxxxxxxxx/send-email-to-creator' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

#### Handling failed 2FA and retry

##### Wrong code retry (phone/app OTP)

If the submitted OTP is invalid, the attempt enters retry mode instead of failing permanently.

* Retry progress: `wrong_2fa_code_retry`
* Definitive error code: `WRONG_2FA`
* Re-submit a fresh code via `PUT /authenticate/{attempt_id}` (no restart needed)

Example poll response while retry is available:

```json
{
  "state": "needs-app-otp",
  "progress": "wrong_2fa_code_retry",
  "lastAttempt": {
    "success": false,
    "error_message": null,
    "error_code": "WRONG_2FA",
    "needs_otp": true,
    "needs_face_otp": false
  }
}
```

##### Other 2FA failure cases

* `lastAttempt.error_message` is populated for terminal failures (for example timeout or upstream verification errors).
* If you submit OTP when none is pending, API returns `400` with: `No pending OTP verification`.
* Recommended behavior:
  1. Keep polling while `completed_at` is `null`.
  2. If `lastAttempt.needs_face_otp` is `true`, take `lastAttempt.face_otp_verification_url`, ask the creator to complete selfie verification in browser, then submit:
     ```json
     { "selfie_verification_completed": true }
     ```
  3. If `state` is `needs-otp` (phone OTP), prompt for SMS code and submit:
     ```json
     { "code": "12345" }
     ```
  4. If `state` is `needs-app-otp` (authenticator app), prompt for app code and submit:
     ```json
     { "code": "123456" }
     ```
  5. If `progress` is `wrong_2fa_code_retry`, prompt user for a new OTP and re-submit.
  6. If attempt is completed with failure, show `error_message` and start a new authentication attempt.

### Option 5: By providing cURL request

This is the manual way to connect your OnlyFans account to our API.

<Callout type="warn">
  We recommend to sign in and enter the cURL request from a **incognito
  window**. Please do NOT sign out account after you've connected it to our API,
  just close the incognito window.
</Callout>

Honestly, it's easier to watch the video below and follow the steps.

<iframe width="100%" height="400px" src="https://www.youtube.com/embed/6fijw-Y6qis" title="" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen className="rounded-md" />