Fanvue API Documentation

The App Manifest is an optional JSON file your app serves at https://<app domain>/app-manifest.json. Any key it contains replaces the matching setting in the Developer Area, so your app type, URLs, scopes, redirect URIs and webhook destinations can live in version control and ship with your code. Every key is defined in the App Manifest reference. You need an off-platform or on-platform app and a domain you control that serves https. An API-only app needs neither an app domain nor a manifest; set its scopes and redirect URIs on the Authentication tab.

What goes where

Every setting the manifest can carry also has a home in the Developer Area, except the post-install URL. Listing copy, images, credentials and pricing have no manifest key, so they stay in the Developer Area whatever your manifest says.

Setting	Developer Area location	Manifest key
App type	App details, app type select (API-only, Off-platform, On-platform)	`access.type`: `embedded` or `off_platform`. An API-only app has no manifest form.
App URL (off-platform)	App details, App URL	`access.url`
Creator landing URL and fan experience URL (on-platform)	App details, Embed settings	`access.url`, `access.fanExperienceUrl`, `surfaces`
Post-install URL	Manifest only	`access.postInstallUrl`
Fan experience presentation	Embed settings, Open as	`surfaces[].presentation`
Scopes and redirect URIs	Authentication tab	`oauth`
Webhook destinations	Events tab	`webhooks`
Name, tagline, icon, description, highlights, preview images, test credentials	App details	none
Client ID and Client Secret	Authentication tab	none
Pricing plans and one-time items	Pricing tab	none

In the Developer Area, a field the manifest sets carries the pill From manifest and a hint to edit it in the manifest instead. A list the manifest sets to [] shows as empty, with a note that the manifest set it that way. Two more pills mark values in transit: Pending review on a scope addition waiting for review, and Not applied yet on a value the last check couldn’t apply. Settings or manifest explains which source wins.

Minimal manifest

Pick the tab for your app type and replace your-app.com with your domain.

On-platform
Off-platform

app-manifest.json

{
  "manifestVersion": 1,
  "access": {
    "type": "embedded",
    "url": "https://your-app.com/embedded"
  }
}

access.url is the page Fanvue loads on the creator’s App Home page when they open your app.

app-manifest.json

{
  "manifestVersion": 1,
  "access": {
    "type": "off_platform",
    "url": "https://your-app.com"
  }
}

access.url is where creators open your app.

To keep scopes and redirect URIs in your repo too, add an oauth block. Each key you include replaces the Authentication tab’s value.

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

Existing apps

An existing app keeps working when you add a manifest. Your live redirect URIs, scopes and webhook destinations stay as they are, and the Authentication and Events tabs keep showing them. Nothing is replaced until you check a manifest that has that key, and a manifest without oauth or webhooks leaves your settings in charge. That lets you move fields into the manifest one at a time. To move fields into the manifest, start from your current configuration:

On the Versions tab, click Download current config. You get an app-manifest.json built from the values in use on your app.
Serve the file unchanged at https://<your app domain>/app-manifest.json.
Set your app domain on the App details tab. The first check reports Up to date.
Edit the file from there, deploy and click Check now.

Download current config leaves a key out when your current configuration has something the manifest can’t hold, so the first check can’t change it:

Key left out	Why
`oauth`	A redirect URI that breaks the redirect URI rules, for example one that contains `*` or uses `http://` on a host other than `localhost`, `127.0.0.1` or `[::1]`
`webhooks`	A destination with a topic the manifest doesn’t support, a URL that breaks the webhook endpoint rules, or a second destination for the same topic
`surfaces`	A published surface other than the four the manifest supports

To bring a field under the manifest, change that setting to one the manifest allows and add the block. If your app has no app URL yet, the download fails with an export error. Write a manifest from Minimal manifest instead.

Connect your app domain

Your app domain links the manifest to your app. Fanvue always reads the manifest from:

https://<your app domain>/app-manifest.json

Enter the domain, for example your-app.com, in the App domain field on your app’s App details tab. The field shows the Manifest URL it will read. It saves when you leave the field or press Enter, and Fanvue checks your manifest straight away. A free subdomain from a static host works, for example my-app.vercel.app, my-app.github.io or my-app.pages.dev. The domain must follow these rules:

A domain only, with no https://, path, port, query, username or password. Subdomains such as app.your-app.com are allowed.
A public name, not an IP address. Enter internationalised domains in their xn-- form.
Not a reserved or internal name, as listed under Reserved domain names.
One app per domain. A domain another app already uses is refused.

Reserved domain names

Refused	Values
Names	`localhost`, `metadata.google.internal`
Suffixes	`.local`, `.internal`, `.localhost`
Zones, as the whole domain or a suffix	`test`, `invalid`, `arpa`, `onion`, `on.aws`, `fanvue.com`, `fanvue.dev`

For example, app.fanvue.com is refused and myfanvue.com is allowed.

The domain is locked while a submission is in review. To remove it, clear the field and confirm Remove domain; Removing the domain lists what changes.

Serving requirements

Requirement	Value
URL	Exactly `https://<your app domain>/app-manifest.json`, on port 443
Response status	`200`. A `304 Not Modified` is accepted in reply to a request that sent `If-None-Match`.
Redirects	Not followed. Any `3xx` response other than that `304` gives the status Rejected. Serve the file at the exact URL.
`Content-Type`	`application/json`, `text/json`, or any `+json` type. Parameters such as `charset=utf-8` are accepted.
Body	Valid UTF-8 JSON, 256 KB (262,144 bytes) maximum
Response time	8 seconds for the whole response
DNS	The domain must resolve to a public IP address

Fanvue sends a GET with Accept: application/json and User-Agent: Fanvue-App-Manifest/1, and no cookies or authentication. If your last response had an ETag, the next check sends it back in If-None-Match, and you can reply 304 Not Modified when the file hasn’t changed. Behind a firewall or bot protection, allow requests with the Fanvue-App-Manifest/1 user agent to reach /app-manifest.json.

When Fanvue checks your manifest

Fanvue checks your manifest at two moments only:

when you save your app domain
when you click Check now on the Versions tab

Fanvue never checks on a schedule, so click Check now after you deploy a change to your manifest. Saving a domain and clicking Check now are each limited to 5 times a minute and 60 times an hour, across all your apps. If a check is already running for your app, wait for it to finish before you click Check now again. The App manifest panel on the Versions tab shows the result:

a status
the Manifest URL
the Contract version, which is the manifestVersion of the last manifest Fanvue read, shown as v1
Manages, the sections your manifest sets
any issues

If you removed a key since the last check, the result also lists the fields that switched back to your settings, under “Now using your settings values for: …”. Manifest statuses and errors explains each status and issue. A failed check never breaks your live app. If Fanvue can’t read your manifest, or the file fails validation, the values in use stay as your last successful check left them, and nothing switches back to your settings values. Fix the file, deploy it and click Check now. There’s one exception. If your file goes over the webhook destination limit, the check shows Invalid, but its oauth changes are already applied.

When changes take effect

Section	When it takes effect
`oauth.redirectUris`	On the next successful check. Redirect URIs need no review.
`oauth.scopes`	Removals on the next successful check. Additions apply on check until your first submission is in review. After that, an addition waits until the submission that requests it is approved.
`webhooks`	On the next successful check, when `webhooks` is present. A destination whose topic needs a scope your app lacks waits until the scope is granted.
`access` and `surfaces`	Staged onto your store draft on every successful check while nothing is in review. The Debug tab and Embed settings show that draft. Submit for review sends it, and a live app changes when the submission is approved.

Values you set on the Authentication and Events tabs take effect when you save, unless your manifest sets that field. A scope added on the Authentication tab after your app is published also waits for review, and the tab shows it as Pending review.

Adding a scope makes every user authorise your app again

When a scope is added to your app, from the manifest or the Authentication tab, Fanvue revokes every existing user consent for your app. Each user must authorise again on their next use, and calls that need the new scope fail until they do. On-platform apps show the creator the consent screen the next time they open your app. Removing a scope revokes nothing.To add scopes safely, first ship code that sends a user back through sign-in when their consent is revoked, then add all the new scopes in one change.

Once your app is live, a check that changes access or surfaces sets the Versions tab to Out of sync, and the App details tab shows Live · manifest changed with a list of the changes. Your live app keeps its published configuration until you resubmit and the new version is approved; see Ship manifest changes to a live app.

Settings or manifest

Scopes, redirect URIs and webhook destinations have two possible sources: your app’s settings on the Authentication and Events tabs, and the manifest. If a key is present in your manifest, the manifest sets that field.

Rule	Detail
Manifest wins	When `oauth.scopes`, `oauth.redirectUris` or `webhooks.destinations` is present in your last successful manifest, your app uses that value. Otherwise it uses your settings value.
Whole lists	Each list is replaced whole, never merged. The file means “exactly these”, so an entry missing from the file isn’t in use.
`[]` is a value	An empty list in the manifest overrides your settings and clears the field. Only an absent key falls back to your settings.
Failed checks	An Unreachable, Invalid or Rejected check never changes the values in use. The last good manifest keeps applying.
Removing a key	Your settings value takes effect on the next successful check, and the check result lists the fields that switched.
Removing the domain	Scopes, redirect URIs and webhook destinations switch back to your settings values. See Removing the domain.
Scope additions after publish	Wait for review, from either source. The Authentication tab shows them as Pending review.

Your settings stay editable and saved while the manifest sets a field. The tab marks the field From manifest and shows the manifest’s value. access and surfaces replace the matching App details fields on every successful check. When surfaces is present, your file is the whole list, and fan_chat or fan_post surfaces missing from it are removed when your next version is approved. creator_landing and fan_experience always follow access and are never removed this way. To submit for review, your app needs at least one redirect URI in use, from the Authentication tab or the manifest. The Events tab stays editable. When your manifest has webhooks.destinations, the tab marks the list From manifest, and edits you make there stay saved but aren’t in use while the manifest sets the list.

Staging and production

A manifest has no environments block, so use a separate app for each environment, each with its own domain, for example staging.your-app.com and your-app.com. One domain can belong to one app only.

Versioning

The current manifestVersion is 1. Fanvue rejects keys it doesn’t recognise, so check the reference before you add one.

First publish with a manifest

A first-publish gate applies only when an app domain is stored. An app that has never been published can submit only while its manifest status is Up to date or Out of sync. Otherwise Submit for review is blocked until you fix the manifest errors on the Versions tab, or remove the app domain on App details. An app with no domain publishes from its settings alone, and an app that has already been approved is never blocked by this gate.

Removing the domain

Clearing the App domain field and confirming Remove domain stops every check, and changes the following:

Scopes, redirect URIs and webhook destinations the manifest set switch back to the values in your app’s settings.
Embed URLs and the post-install URL the manifest set on your store draft go back to your live app’s values, or are removed where your live app has none. On an app that has never been published they are removed.
A fan experience URL stays until you remove it in Embed settings.
A draft that is with a reviewer isn’t changed. Update its values in app settings after the review.

Every value stays editable in app settings after the domain is removed.

Removing a fan experience

A check refuses any manifest that drops the fan surface, because removing the surface takes paid access away from fans and a check can’t confirm that impact unattended. Manifest statuses and errors lists the exact message. Remove the surface in Embed settings, or switch the app type to API-only on App details. Both ask you to confirm the impact on fans who hold paid access before saving. Changing the fan experience URL to a different URL isn’t guarded. See Taking paid access away.

Overview

Builder SDK

Fan experiences

App Manifest

Submit and review

Keep app configuration in your repo with the App Manifest

What goes where

Minimal manifest

Existing apps

Connect your app domain

Serving requirements

When Fanvue checks your manifest

When changes take effect

Adding a scope makes every user authorise your app again

Settings or manifest

Staging and production

Versioning

First publish with a manifest

Removing the domain

Removing a fan experience

See also

​What goes where

​Minimal manifest

​Existing apps

​Connect your app domain

​Serving requirements

​When Fanvue checks your manifest

​When changes take effect

Adding a scope makes every user authorise your app again

​Settings or manifest

​Staging and production

​Versioning

​First publish with a manifest

​Removing the domain

​Removing a fan experience

​See also

What goes where

Minimal manifest

Existing apps

Connect your app domain

Serving requirements

When Fanvue checks your manifest

When changes take effect

Settings or manifest

Staging and production

Versioning

First publish with a manifest

Removing the domain

Removing a fan experience

See also