Connect OnlyFans account

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

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.

Steps to connect your OnlyFans account:

1. Go to the OnlyFans API Console -> 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

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

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 (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

Phone-only flow (includes TestFlight install)

Step 1a — Start the session from the Dashboard

1. Go to the OnlyFans API Console -> 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 with auth_type set to mobile_app and a display_name for the account:

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:

{
  "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
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

npm install @onlyfansapi/auth

2) Create a client session token

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

POST /client-sessions

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

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);
  },
});

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.

1) Start authentication

POST /authenticate

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:

{
  "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}

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}

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:

{
  "selfie_verification_completed": true
}

4) Optional: send OTP verification email to creator

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

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:

{
  "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:

     { "selfie_verification_completed": true }

  3. If state is needs-otp (phone OTP), prompt for SMS code and submit:

     { "code": "12345" }

  4. If state is needs-app-otp (authenticator app), prompt for app code and submit:

     { "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.

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