Authentication

The API authenticates every request with an API key, sent as a Bearer token.

Authorization: Bearer fsq_live_7Q2mXc9LkP4dR8sTvB1nY6wZ3hJ5gF0a

A missing header returns 401 missing_authorization; a malformed, unknown or revoked key returns 401 invalid_api_key; a key past its expiration date returns 401 expired_api_key.

Create a key

Keys are created in the Fansquare app by the agency owner, in Settings › Developer API › API. When you create a key, you choose:

• a name, to recognise it later (for example "BI integration");

• its access: Read only (read:*), Full access (*), or Custom, a selection among the twelve scopes on creators, employees, fans, orders, messages, analytics, insights, publications, assignments and AI locks;

• its creators: all the creators of the agency, including those added later, or a fixed selection;

• an expiration, optional: in 30 days, 90 days, one year, or never.

The webhook and AI request scopes are not offered in Custom: read:webhooks and read:ai_requests come with Read only, write:webhooks and write:ai_requests with Full access.

The key is displayed once, at creation. Fansquare only keeps a hash of it: a lost key cannot be shown again. Revoke it and create a new one.

An agency holds at most 20 keys that are not revoked, expired keys included. Revoke one to create another.

Key format

A key starts with fsq_live_ followed by 32 letters and digits. The first characters are shown in the app to identify a key without revealing it.

Scopes

Each key carries scopes. A request to an endpoint whose scope the key lacks returns 403 missing_scope, with the scope it needs in required_scope. Every endpoint page shows its required scope.

Three shortcuts cover several scopes: read:* (every read scope), write:* (every write scope) and * (everything).

Creators covered by a key

A key covers either every creator of the agency, including creators added later, or a fixed selection of creators. A fixed selection never grows: if the agency adds a creator, the key does not see it.

Data of a creator the key does not cover behaves as if it did not exist: it is absent from lists and totals, and a direct request returns 404, exactly like a resource that does not exist.

Webhook endpoints follow the same rule. A key limited to some creators only sees the endpoints that cover its own creators and no other, and an endpoint it creates or edits covers its creators at most: an empty creator list then means the creators of the key.

Employees and tags belong to the agency, not to a creator: every key sees all of them.

Inspect a key

GET /v1/me returns the agency, the scopes and the creators of the key you are calling with. It needs no scope, so any valid key can call it: use it to check a key at startup.

Revoke a key

Revoke a key from the same settings page. It stops working within five minutes, the time for every server of the API to drop it from its cache.