Fanvue API Documentation

A scope names one area of a Fanvue account your app may read or write. You pick scopes on your app, the user grants them at consent, and the API checks them on every request. Use the tables below to decide what to request: what each scope unlocks, which accounts can grant it, and which webhook events it gates. The read:experience and write:experience scopes are for fan experiences.

Scope table

Scope	Grants	Account types
`read:chat`	Read chat conversations and messages, including chat lists and message history.	Fan, creator, agency
`read:creator`	Read creator profiles and creator-specific information.	Creator, agency
`read:experience`	Exchange a launch token, list experiences, read priced actions, action purchases and action definitions.	Fan, creator, agency
`read:fan`	Read fan-related data within the platform.	Creator, agency
`read:insights`	Read analytics, metrics and insights data.	Creator, agency
`read:media`	Read media files and content assets.	Fan, creator, agency
`read:post`	Read posts, including post details, comments, likes and tips.	Creator, agency
`read:self`	Read your own user profile, including basic account details and settings.	Fan, creator, agency
`read:tracking_links`	Read tracking links and the users associated with them, including per-user tracking metadata.	Creator, agency
`write:chat`	Create chats and send messages. Required for every chat action that modifies data.	Fan, creator, agency
`write:creator`	Modify creator profiles, settings and creator-specific data.	Creator, agency
`write:experience`	Mint request tokens, charge a fan’s wallet for a priced action with `POST /experiences/{experienceUuid}/action-purchases`, and publish, update and unpublish experiences directly, including setting prices.	Fan, creator, agency
`write:media`	Upload, modify and manage media files and content assets. Also required for vault folder management.	Fan, creator, agency
`write:post`	Create, edit and manage posts on behalf of users.	Creator, agency
`write:tracking_links`	Create and delete tracking links.	Creator, agency
`read:agency`	Read agency information, including the agency’s team members.	Agency admin
`write:agency`	Manage agency team members and invites, including inviting new team members and creators.	Agency admin

Scopes by account type

Every Fanvue account can act as a fan, and the creator, agency and agency admin roles add to that. “Agency” in the scope table means any agency team member, whose creator-context scopes work against the creators assigned to them. “Agency admin” is the stricter tier that also unlocks the agency-management scopes.

Account type	Grantable scopes
Fan	`read:self`, `read:chat`, `write:chat`, `read:media`, `write:media`, `read:experience`, `write:experience`
Creator	Every fan scope plus `read:post`, `write:post`, `read:fan`, `read:insights`, `read:tracking_links`, `write:tracking_links`, `read:creator`, `write:creator`
Agency team member	The same set as a creator, exercised against assigned creators through `/creators/{creatorUserUuid}/...`
Agency admin	Every agency team member scope plus `read:agency`, `write:agency`

Consent drops the scopes the consenting account cannot use and grants the rest. For example, a fan account that authorises an app requesting every scope receives only read:self and the chat, media and experience scopes. The token’s scope field shows what was granted, so read it rather than assuming the request succeeded in full. When none of the requested API scopes is usable by the account, consent is rejected with access_denied and the description Application is not compatible with your account type. A request for the identity scopes alone passes.

System scopes

openid, offline_access and offline are system scopes. They are always allowed, are not listed on the Authentication tab and are added to every grant. On an off-platform or API-only app, request them in your authorisation URL, because offline_access is what returns a refresh token. An on-platform app doesn’t request them: on the embedded authorise-on-behalf path the platform adds openid and offline_access itself.

Scopes and webhook events

Creating or listing a webhook subscription needs read:self. Each event you subscribe to also needs its own scope on the token, or the subscription request fails.

Scope	Events it gates
`read:chat`	`creator.message.received`, `creator.message.sent`, `creator.message.mass_sent`, `creator.message.read`, `creator.message.read_by_fan`, `creator.message.deleted`, `creator.message.reaction`, `creator.chat.marked_unread`, `creator.fan.status_changed`, `creator.fan.presence_changed`, and the legacy `message.received` and `message.read`
`read:creator`	`creator.payment.`, `creator.subscription.`, `creator.follow.created`, `creator.refund.created`, `creator.dispute.`, `creator.reward.`, every `checkout_link.` event, `payout.paid`, `payout.failed`, and the legacy `follow.new`, `purchase.new`, `subscription.` and `tip.new`
`read:post`	`creator.post.liked`, `creator.post.commented`
`read:experience`	`creator.experience_subscription.activated`, `creator.experience_subscription.deactivated`
`read:self`	`creator.logout`, every `app.` event including `app.experience.action.`

The event catalogue lists every event with its payload.

Setting scopes

Select your scopes on your app’s Authentication tab in the Developer Area. They apply when you save. To keep them in your repository instead, set the oauth.scopes key in your App Manifest. They apply on the next manifest check, and while the key is present the Authentication tab marks your own selection as not in use and shows the manifest value.

app-manifest.json

"oauth": {
  "scopes": ["read:self", "read:chat"],
  "redirectUris": ["https://your-app.com/api/oauth/callback"]
}

Request only the scopes your app uses, because users see every one you ask for on the consent screen. The scopes your code requests at authorisation must be among your app’s configured scopes, or the request fails with invalid_scope. Adding a scope makes every existing user authorise your app again. On a listed app, a scope addition is held until the submission that requested it is approved; the Authentication tab shows it as Pending review until then. See When changes take effect before you add one.

Insufficient scope errors

A request whose access token lacks a required scope returns 403 with this body:

{
  "error": "Insufficient scopes"
}

Retrying the request unchanged returns the same 403. Add the scope on the Authentication tab or in oauth.scopes, request it in your authorisation URL, then have the user reconnect. Error responses lists the API’s other error bodies.

Start here

Authentication

API concepts

Guides

Scopes