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

# Authorize

> Build the authorization request and handle the callback

OFAuth uses OAuth 2.0 to ask users for permission to share accounts with your app. After approval, your backend (your app's server) exchanges a one-use code for tokens.

PKCE is a security check that protects the code exchange with a secret value called a verifier. The `state` value ties the callback to the browser session that started the request. Keep the client secret, verifier, and state record on your backend.

## Create the authorization request

Build the URL on your backend and send the user to it.

```http theme={null}
GET https://link.ofauth.com/v3/authorize
```

| Parameter | Requirement |
| - | - |
| `response_type` | Use `code`. |
| `client_id` | The client ID for the environment you want to use. |
| `redirect_uri` | The exact callback URL registered for that client. |
| `state` | A random, one-use value. Returned on the redirect. |
| `code_challenge` | The SHA-256 hash of the PKCE verifier, encoded as base64url (43 characters). |
| `code_challenge_method` | Use `S256`. |
| `scope` | Space-separated permission names, called scopes. Every successful code exchange returns a refresh token. See [scopes](https://docs.ofauth.com/v3/api-reference/authentication.md#scopes). |

Live consent displays the purpose from your approved app configuration. Renewed consent preserves existing grants; additional permissions apply only to selected accounts.

Each parameter may appear once. Unknown or repeated parameters return `invalid_request`.

You do not send `resource`. If your OAuth client library always sends one, it must be `https://api.ofauth.com/v3`; any other value returns `invalid_request`.

```typescript TypeScript SDK theme={null}
import { OFAuthLink } from "@ofauth/onlyfans-sdk"

const link = new OFAuthLink({ clientId, clientSecret, redirectUri })
const attempt = await link.createAuthorizationUrl({ scopes: ["profile:read"] })
// Save state and verifier with your trusted user, browser session, expiry,
// and registration version before redirecting to attempt.url.
```

```bash curl theme={null}
# Build the URL; open it in the user's browser.
VERIFIER=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)

echo "https://link.ofauth.com/v3/authorize?\
response_type=code&\
client_id=$OFAUTH_SANDBOX_CLIENT_ID&\
redirect_uri=https%3A%2F%2Fdeveloper.example.com%2Foauth%2Fofauth%2Fcallback&\
state=$STATE&\
code_challenge=$CHALLENGE&\
code_challenge_method=S256&\
scope=profile%3Aread%20messages%3Aread"
```

Your application saves callback state and the verifier. [The Express example](https://github.com/ofauth-source/example-express-oauth) binds them to the initiating application user and browser session. Send only the authorization URL to the browser.

## Redirect URI rules

Redirect URIs are registered per environment client in the dashboard. The `redirect_uri` parameter must match a registered value exactly.

| Rule | Sandbox and Test | Live |
| - | - | - |
| HTTPS with a domain hostname | Allowed | Required |
| `http://127.0.0.1:<port>/...` or `http://[::1]:<port>/...` | Allowed | Rejected |
| `http://localhost` or any other `http://` host | Rejected | Rejected |
| IP address, `localhost`, or `*.localhost` over HTTPS | Rejected | Rejected |
| Fragment (`#`) | Rejected | Rejected |
| Wildcard (`*`) | Rejected | Rejected |
| Userinfo (`user:pass@`) | Rejected | Rejected |

Use a complete URL with no alternate spelling or formatting. Register the exact string you will send. Each client can have up to 20 redirect URIs.

## Open the system browser

Open OFAuth in the browser itself, rather than inside your app's page.

| Platform | Browser option |
| - | - |
| Web | The system browser or a top-level browser window. |
| iOS | `ASWebAuthenticationSession`. |
| Android | A Custom Tab. |

Do not use an iframe or `postMessage`. Do not send the client secret or PKCE verifier to the browser or native app.

## What the user sees

1. OFAuth establishes current owner authority. Supported guest connection does not require an OFAuth signup.
2. The user links an OnlyFans account, or chooses accounts they or their organization already linked.
3. The user approves the scopes you requested for the chosen accounts.
4. OFAuth redirects to your callback.

A linked account belongs to its owner, not to your integration. The owner can share the same account with several apps, and can revoke your access from the OFAuth dashboard at any time.

### Accounts linked later

The consent screen can offer the owner **Also share accounts I link later**. It is off by default and hidden for guests. If the owner turns it on, accounts are added to your authorization with the scopes they approved, and you receive `authorization.updated` with `reason: "auto_added"`:

* In Live, each OnlyFans account the owner newly links afterwards is added.
* In Test, only accounts designated as test accounts are added, when they are designated, and only if they were linked after auto-add was turned on.
* Only new accounts are added. Reconnecting an existing account does not add it, and an account the owner removed from your authorization is never added back.
* The owner can turn the setting off from the third-party apps page in their dashboard. Accounts already shared stay shared.

## Handle the callback

OFAuth returns only to the exact registered redirect URI.

| Result | Query parameters |
| - | - |
| Success | `code=<opaque>&state=<original>&iss=<issuer>` |
| Denial or cancellation | `error=access_denied&state=<original>` |
| Expired or invalid request | `error=invalid_request&state=<original>` |

If the request cannot be tied to a registered redirect URI, OFAuth shows the error instead of redirecting (`invalid_request`, `invalid_scope`, `unauthorized_client`, or `access_denied` with a `reason`).

The authorization code expires after 5 minutes and is single-use.

Your app or auth framework stores state with the initiating user and browser session and accepts it only once. Reject mismatched sessions without consuming a legitimate attempt. Validate `iss` against `https://api.ofauth.com/v3/link`. Perform these checks before [exchanging the code](https://docs.ofauth.com/v3/api-reference/link/tokens.md#exchange-the-authorization-code).

```typescript TypeScript SDK theme={null}
// pending has already been atomically consumed for this user and session.
const { code } = link.parseCallback(request.url, pending.state)
const tokens = await link.exchangeCode({ code, codeVerifier: pending.codeVerifier })
// Save only while the registration version still matches.
```

## Return to a native app

The native app asks its backend for the authorization URL. It opens that URL in `ASWebAuthenticationSession` or a Custom Tab.

After the HTTPS callback, the backend can open a one-use Universal Link or App Link. Put only a random reference to your app's sign-in attempt in that link. The reference must not reveal any credentials. Keep the authorization code, OAuth state, tokens, client secret, and PKCE verifier on the backend.

Do not use a custom URL protocol. Do not send OFAuth directly to a native callback. Do not exchange tokens from a public native client.

## Requesting more scopes or accounts later

Request the additional scopes your feature needs. Existing creator grants and accounts stay shared. The owner selects which accounts receive the new scopes; unselected accounts keep their existing permissions. Removing access is a separate action in OFAuth. The authorization keeps its `authorization_id`, and you receive `authorization.updated` with `reason: "consent_updated"`. Access calls that need a scope you have not been granted fail with `missing_scope` or `additional_consent_required`. See [Errors](https://docs.ofauth.com/v3/api-reference/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.