status (connected, needs_reconnect, or disconnected) and the lifecycle webhooks that report changes. When an Access call fails, branch on the error’s recovery.action. An expired OnlyFans session needs the account owner to reconnect; a revoked authorization or a failed refresh with invalid_grant needs a new authorization.
There are two different things that can stop working. The OnlyFans session behind one linked account can expire, while your access to it remains. Or your access itself can end: the owner revokes your app, removes an account, or a credential is revoked or expires.
Frequently Asked Questions
What doesneeds_reconnect mean? The OnlyFans session for that linked account is no longer usable, but your access remains. Access calls return linked_account_reconnect_required. The owner must reconnect, and you receive linked_account.reconnected when it works again. The linked account id stays the same.
Can two instances refresh together? Yes. The authenticated client uses the same stable refresh token. Each successful refresh returns its own access token. Retry a lost refresh response with the same token.
What does invalid_grant on refresh mean? The credential expired, was revoked, or does not belong to the authenticated client. Restart authorization for that customer. A transient network or storage error does not prove revocation.
If I ask for more scopes, do I get a new authorization? An existing authorization keeps its authorization_id. New consent adds permissions to the selected accounts. You receive authorization.updated with reason: "consent_updated".
How long does a refresh token last? 90 days without a successful authenticated refresh. Resource requests do not extend the window.
What do the linked account statuses mean?
Read the current status from
GET /v3/linked-accounts or GET /v3/linked-accounts/{id}.
Which webhooks tell me something changed?
db stands in for your persistence layer. Deduplicate on eventId and apply events per linked account in order before calling this.
How do I recover from an Access error?
Read the error’s recovery action, then choose the matching next step:
Log
requestId with failures so support can trace the request. Before repeating a post, story, or message whose outcome is uncertain, check whether it completed.
How do I refresh across processes?
Let your auth framework or application persist tokens and supply a current access token to the SDK. Refresh with the same stable client-bound token. No mandatory database lock, attempt marker, or replay journal is needed. Use conditional writes when the customer replaces or disconnects a registration. Include the client and application user in your storage key. An unavailable Developer plan or suspended client needs action by the application owner, not new customer consent.How do I bring the user back?
Forrestart_authorization, invalid_grant, or authorization.revoked, send the user through the authorization flow again. If you only lost a refresh token, the user sees the accounts and scopes they already approved. Request the permissions needed by your feature. Consent adds permissions only to the accounts the user selects. Check the current account grants before continuing.