# Quick Start (/auth/quickstart)



import { Tabs, Tab } from "fumadocs-ui/components/tabs";
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";

## Overview

This guide will walk you through implementing `@onlyfansapi/auth` in your application. The authentication library provides a simple, secure way to authenticate users with their OnlyFans accounts.

## Before You Start

<Callout type="info">
  Make sure you've completed the [installation](/auth/installation) steps first. You'll need:

  * The package installed in your project
  * An API key to create client session tokens
  * A client session token (starts with `ofapi_cs_`) to use with the library
</Callout>

## Basic Usage

The library exports a single function `startOnlyFansAuthentication` that handles the entire authentication flow. When called, it opens a secure iframe modal where users can authenticate with their OnlyFans account.

### Import

```typescript twoslash
import { startOnlyFansAuthentication } from '@onlyfansapi/auth';
```

### Function Signature

```typescript
const startOnlyFansAuthentication: (clientSessionToken: string, options: {
    onSuccess: (data: AuthSuccessData) => void;
    onError: (error: AuthFailureError) => void;
    onContinue?: () => void;
}) => void
```

**Parameters:**

* `clientSecret` (string, required): Your client session token obtained from the [Create Client Session](/api-reference/client-sessions/create-client-session) API endpoint
* `options.onSuccess` (function, required): Callback invoked when authentication succeeds
* `options.onError` (function, required): Callback invoked when authentication fails

## Framework Examples

<Tabs items={['React', 'Vue', 'Svelte', 'Angular', 'Vanilla JS']}>
  <Tab value="React">
    ```tsx
    import React, { useState } from 'react';
    import { startOnlyFansAuthentication } from '@onlyfansapi/auth';

    export default function AuthComponent() {
      const [isLoading, setIsLoading] = useState(false);
      const [authData, setAuthData] = useState(null);
      const [error, setError] = useState(null);

      const handleAuthentication = () => {
        setIsLoading(true);
        setError(null);
        
        startOnlyFansAuthentication('ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', {
          onSuccess: (data) => {
            console.log('Authentication successful:', data);
            setAuthData(data);
            setIsLoading(false);
            // data.accountId - The authenticated account ID
            // data.username - The authenticated username
            // data.response - Full response from the API
          },
          onError: (error) => {
            console.error('Authentication failed:', error);
            setError(error);
            setIsLoading(false);
            // error.message - Error message
            // error.code - Error code (if available)
            // error.details - Additional error details (if available)
          },
        });
      };

      return (
        <div className="auth-container">
          <button 
            onClick={handleAuthentication}
            disabled={isLoading}
            className="auth-button"
          >
            {isLoading ? 'Authenticating...' : 'Connect OnlyFans Account'}
          </button>
          
          {authData && (
            <div className="success-message">
              <h3>Authentication Successful!</h3>
              <p>Account ID: {authData.accountId}</p>
              <p>Username: {authData.username}</p>
            </div>
          )}
          
          {error && (
            <div className="error-message">
              <h3>Authentication Failed</h3>
              <p>{error.message}</p>
            </div>
          )}
        </div>
      );
    }
    ```
  </Tab>

  <Tab value="Vue">
    ```vue
    <template>
      <div class="auth-container">
        <button 
          @click="handleAuthentication"
          :disabled="isLoading"
          class="auth-button"
        >
          {{ isLoading ? 'Authenticating...' : 'Connect OnlyFans Account' }}
        </button>
        
        <div v-if="authData" class="success-message">
          <h3>Authentication Successful!</h3>
          <p>Account ID: {{ authData.accountId }}</p>
          <p>Username: {{ authData.username }}</p>
        </div>
        
        <div v-if="error" class="error-message">
          <h3>Authentication Failed</h3>
          <p>{{ error.message }}</p>
        </div>
      </div>
    </template>

    <script setup>
    import { ref } from 'vue';
    import { startOnlyFansAuthentication } from '@onlyfansapi/auth';

    const isLoading = ref(false);
    const authData = ref(null);
    const error = ref(null);

    const handleAuthentication = () => {
      isLoading.value = true;
      error.value = null;
      
      startOnlyFansAuthentication('ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', {
        onSuccess: (data) => {
          console.log('Authentication successful:', data);
          authData.value = data;
          isLoading.value = false;
        },
        onError: (err) => {
          console.error('Authentication failed:', err);
          error.value = err;
          isLoading.value = false;
        },
      });
    };
    </script>
    ```
  </Tab>

  <Tab value="Svelte">
    ```svelte
    <script>
      import { startOnlyFansAuthentication } from '@onlyfansapi/auth';

      let isLoading = false;
      let authData = null;
      let error = null;

      function handleAuthentication() {
        isLoading = true;
        error = null;
        
        startOnlyFansAuthentication('ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', {
          onSuccess: (data) => {
            console.log('Authentication successful:', data);
            authData = data;
            isLoading = false;
          },
          onError: (err) => {
            console.error('Authentication failed:', err);
            error = err;
            isLoading = false;
          },
        });
      }
    </script>

    <div class="auth-container">
      <button 
        on:click={handleAuthentication}
        disabled={isLoading}
        class="auth-button"
      >
        {isLoading ? 'Authenticating...' : 'Connect OnlyFans Account'}
      </button>
      
      {#if authData}
        <div class="success-message">
          <h3>Authentication Successful!</h3>
          <p>Account ID: {authData.accountId}</p>
          <p>Username: {authData.username}</p>
        </div>
      {/if}
      
      {#if error}
        <div class="error-message">
          <h3>Authentication Failed</h3>
          <p>{error.message}</p>
        </div>
      {/if}
    </div>
    ```
  </Tab>

  <Tab value="Angular">
    ```typescript
    import { Component } from '@angular/core';
    import { startOnlyFansAuthentication } from '@onlyfansapi/auth';

    @Component({
      selector: 'app-auth',
      template: `
        <div class="auth-container">
          <button 
            (click)="handleAuthentication()"
            [disabled]="isLoading"
            class="auth-button"
          >
            {{ isLoading ? 'Authenticating...' : 'Connect OnlyFans Account' }}
          </button>
          
          <div *ngIf="authData" class="success-message">
            <h3>Authentication Successful!</h3>
            <p>Account ID: {{ authData.accountId }}</p>
            <p>Username: {{ authData.username }}</p>
          </div>
          
          <div *ngIf="error" class="error-message">
            <h3>Authentication Failed</h3>
            <p>{{ error.message }}</p>
          </div>
        </div>
      `
    })
    export class AuthComponent {
      isLoading = false;
      authData: any = null;
      error: any = null;

      handleAuthentication() {
        this.isLoading = true;
        this.error = null;
        
        startOnlyFansAuthentication('ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', {
          onSuccess: (data) => {
            console.log('Authentication successful:', data);
            this.authData = data;
            this.isLoading = false;
          },
          onError: (error) => {
            console.error('Authentication failed:', error);
            this.error = error;
            this.isLoading = false;
          },
        });
      }
    }
    ```
  </Tab>

  <Tab value="Vanilla JS">
    ```html
    <!DOCTYPE html>
    <html>
    <head>
      <title>OnlyFans API Auth</title>
    </head>
    <body>
      <div class="auth-container">
        <button id="auth-button" class="auth-button">
          Connect OnlyFans Account
        </button>
        
        <div id="success-message" style="display: none;">
          <h3>Authentication Successful!</h3>
          <p id="account-id"></p>
          <p id="username"></p>
        </div>
        
        <div id="error-message" style="display: none;">
          <h3>Authentication Failed</h3>
          <p id="error-text"></p>
        </div>
      </div>

      <script type="module">
        import { startOnlyFansAuthentication } from '@onlyfansapi/auth';

        const authButton = document.getElementById('auth-button');
        const successMessage = document.getElementById('success-message');
        const errorMessage = document.getElementById('error-message');

        authButton.addEventListener('click', () => {
          authButton.disabled = true;
          authButton.textContent = 'Authenticating...';
          errorMessage.style.display = 'none';
          
          startOnlyFansAuthentication('ofapi_cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', {
            onSuccess: (data) => {
              console.log('Authentication successful:', data);
              document.getElementById('account-id').textContent = 
                'Account ID: ' + data.accountId;
              document.getElementById('username').textContent = 
                'Username: ' + data.username;
              successMessage.style.display = 'block';
              authButton.disabled = false;
              authButton.textContent = 'Connect OnlyFans Account';
            },
            onError: (error) => {
              console.error('Authentication failed:', error);
              document.getElementById('error-text').textContent = error.message;
              errorMessage.style.display = 'block';
              authButton.disabled = false;
              authButton.textContent = 'Connect OnlyFans Account';
            },
          });
        });
      </script>
    </body>
    </html>
    ```
  </Tab>
</Tabs>

## Response Data

The library provides TypeScript types for better type safety. Import them if needed:

```typescript
import type { AuthSuccessData, AuthError } from '@onlyfansapi/auth';
```

### Success Response

When authentication is successful, the `onSuccess` callback receives an `AuthSuccessData` object:

```typescript
interface AuthSuccessData {
  accountId: string;    // The authenticated OnlyFans account ID
  username: string;     // The authenticated OnlyFans username
  response: object;     // Full response object from the API containing additional metadata
}
```

**Example usage:**

```typescript
onSuccess: (data) => {
  // Store the account ID for future API requests
  localStorage.setItem('ofAccountId', data.accountId);
  
  // Redirect to dashboard or update UI
  console.log(`Authenticated as ${data.username}`);
}
```

### Error Response

When authentication fails, the `onError` callback receives an `AuthError` object:

```typescript
interface AuthError {
  message: string;       // Human-readable error message
  code?: string;        // Error code (if available) for programmatic handling
  details?: object;     // Additional error details (if available)
}
```

**Common error scenarios:**

* User cancels the authentication flow
* Network connectivity issues
* Invalid or expired client session token
* OnlyFans account access issues

**Example error handling:**

```typescript
onError: (error) => {
  if (error.code === 'AUTH_CANCELLED') {
    // User closed the authentication modal
    console.log('Authentication cancelled by user');
  } else {
    // Handle other errors
    console.error('Authentication failed:', error.message);
    // Display error to user
  }
}
```

## Security

The authentication library implements multiple security measures to protect user data:

* **Origin validation**: All communication with the authentication iframe is validated by origin
* **Domain whitelisting**: Only messages from the configured OnlyFansAPI.com domain are accepted
* **Secure token transmission**: Client session tokens are passed securely via URL parameters
* **HTTPS required**: The library requires HTTPS connections in production environments

## Best Practices

### Storing Client Session Tokens

Store your client session token securely:

```typescript
// ✅ Good: Use environment variables (if using a build tool)
const CLIENT_SECRET = process.env.NEXT_PUBLIC_OFAPI_CLIENT_SECRET;

// ✅ Good: Fetch from your backend API (most secure)
const clientSecret = await fetch('/api/client-secret').then(r => r.json());

// ❌ Bad: Hardcode in your source code
const CLIENT_SECRET = 'ofapi_cs_...';
```

### Error Handling

Always handle both success and error cases:

```typescript
startOnlyFansAuthentication("clientSecret", {
  onSuccess: (data) => {
    // Update your application state
    // Persist authentication data if needed
    // Redirect or update UI
  },
  onError: (error) => {
    // Log errors for debugging
    // Show user-friendly error messages
    // Provide fallback options
  },
});
```

### User Experience

* Show a loading state while authentication is in progress
* Disable the authentication button during the flow to prevent duplicate requests
* Provide clear feedback on success or failure
* Consider adding a "try again" option if authentication fails

## Troubleshooting

### Common Issues

**Authentication modal doesn't open:**

* Ensure your client session token is valid and properly formatted
* Check browser console for any error messages
* Verify that pop-ups aren't blocked by your browser

**"Invalid client secret" error:**

* Verify your client session token is correct (starts with `ofapi_cs_`)
* Check that the token hasn't expired
* Ensure you're using a token created via the [Create Client Session API](/api-reference/client-sessions/create-client-session)

**Network errors:**

* Check your internet connection
* Verify OnlyFansAPI.com is accessible from your network
* Some corporate firewalls may block the authentication iframe

## Next Steps

* Review the [Installation Guide](/auth/installation) if you haven't already
* Check out the [NPM package](https://www.npmjs.com/package/@onlyfansapi/auth) for the latest version and updates
* Visit [onlyfansapi.com/auth](https://onlyfansapi.com/auth) for more information
* Explore the [API Reference](/api-reference) to see what you can do with authenticated accounts