# Connect OnlyFans account (/introduction/guides/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.
Your credentials are securely stored in our database and are never shared with
anyone (not even our engineers can see your credentials).
Steps to connect your OnlyFans account:
1. Go to the [OnlyFansAPI 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
Other proxy countries (DE, FR, IT) have been temporarily removed due to OnlyFans restrictions.
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
```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);
},
});
```
This package handles the OTP / selfie authentication UI flow for you in an embedded modal.
For the full authentication API and package reference, see: [`/auth`](/auth).
### 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.
Base URL for examples below: [https://app.onlyfansapi.com/api](https://app.onlyfansapi.com/api)
#### 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 (phone or 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
}
```
No external mobile app is required for selfie verification. The creator only needs to open
the face\_otp\_verification\_url link in a regular browser on their phone or desktop
and complete the verification steps there.
#### 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 4: By providing cURL request
This is the manual way to connect your OnlyFans account to our API.
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.
Honestly, it's easier to watch the video below and follow the steps.