Agencies: one key for every creator

Agencies on Dropfans manage several accounts — real creators who accepted the agency, and AI personas the agency runs. One API key held by the agency covers all of them:

• The agency endpoints act as the agency itself: list the roster, create personas, invite creators, read revenue across the roster. See the Agencies reference.
• Every creator endpoint (vault, drops, posts, earnings, profile, links, …) acts for one managed account when you add X-Dropfans-Account: <account id>. Without the header, the key acts for the agency’s own account, exactly as before.

1. Get the agency key#

The agency signs in to the Dropfans dashboard as itself (not switched into one of its creators), opens Vault → API Connect and generates a key for your app (or a Personal key for its own scripts). That is the agency’s own key.

A key the agency generates while switched into a creator is that creator’s key: it stays bound to that one account, cannot use the header and cannot call the agency endpoints. Those keys keep working as they always have.

Check which kind you hold with GET /me: the agency’s own key returns isAgency: true.

2. Get the account ids#

GET /api/external/agency/creators lists every managed creator and persona with its id, kind (creator or ai_persona), the agency’s permissions on it and active (whether the header works for it right now). Store the ids — they never change. New personas come from POST /agency/personas, new creators join through an invite.

3. Send X-Dropfans-Account#

# Who am I acting as?
curl "https://www.dropfans.io/api/external/me" \
  -H "Authorization: Bearer $AGENCY_API_KEY" \
  -H "X-Dropfans-Account: cmh4v2q8k0003xy9z7w6v5u4t"

# Create a drop on that persona
curl -X POST "https://www.dropfans.io/api/external/drops" \
  -H "Authorization: Bearer $AGENCY_API_KEY" \
  -H "X-Dropfans-Account: cmh4v2q8k0003xy9z7w6v5u4t" \
  -H "Content-Type: application/json" \
  -d '{"name":"Beach set","price":25,"vaultItemIds":["clxv1a2b30001item"]}'

The request then behaves exactly as if it was sent with that account’s own key: the drop belongs to the persona, the sale is booked on the persona, the links are the persona’s. Every response carries an X-Dropfans-Account header with the id of the account it acted on — assert it if you juggle many accounts. With the header, GET /me returns key.viaAgency: true and the agency in key.managedBy.

Send the account id only. Usernames are refused, because a username can change hands. The header is checked on every request — there is no session to set up or tear down — and a header that cannot be honoured is always an error, never a silent fallback to the agency’s own account.

Permissions#

The agency needs the matching permission on the account, the same switches as in the dashboard (AI personas have all of them):

Each reference page names the permission it needs.

Errors#

Webhooks#

An app that holds an agency’s own key also receives webhook events for every creator and persona that agency manages (accepted management). Those payloads carry data.agencyId next to data.accountId, so you can route them. An app is never sent the same event twice, even if it also holds that creator’s own key.

Rate limits and money#

• Rate limits stay per key: one agency key acting for ten accounts shares one budget. Read the rate-limit headers and spread polling accordingly.
• Buyers always pay on Dropfans: buy links, tip links and the subscribe sheet open the Dropfans checkout (web or Telegram Mini App), never yours. Use the links from GET /links with the header to get each account’s own.
• GET /balance can be negative for agency-managed accounts (internal settlements can pull a bucket below zero). Render it signed; do not clamp to zero.

Next: Sell a drop end-to-end or Connect a creator to your app.