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 four ways:

1. Using our automated login flow
2. Add "Login with OnlyFans" to your app (recommended)
3. Connect using API (programmatic flow)
4. By providing cURL request

Option 1: Using our automated login flow

This is the recommended way to connect your OnlyFans account to our API. 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 OnlyFansAPI 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: Add "Login with OnlyFans" to your app (recommended)

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 3: 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 (phone or 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 4: 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.