Acting for a creator: agencies and CRMs

One key can act for many accounts by naming the creator in the path, /creators/{creatorId}/…:

• An agency’s own key acts for every creator who accepted the agency and every AI persona it runs.
• Your app owner’s own key acts for every account your app created with POST /accounts — as long as the account still holds the key we returned for it, bound to your app. Deleting that key (the creator can, in their dashboard) revokes your access.

Put the creator in the path: every creator endpoint (vault, drops, posts, earnings, profile, links, payout reads, …) is also served at /api/external/v1/creators/{creatorId}/<the same path>. Without it, the key acts for its own account, exactly as before. The agency endpoints, sign-up, webhooks and the CRM dashboard act as the agency or app itself and refuse a creator (400 creator_scope_not_allowed).

1. Get the right 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.

For a CRM, use your app owner’s own key — the same one that calls POST /accounts. Keys an agency minted for its creators never act for anyone else.

2. Get the account ids#

GET /api/external/v1/creators lists every account your key can act for, with its relationship (managed, ai_persona or onboarded), your permissions on it, active (whether creator-scoped calls work for it right now) and its creatorPath. Store the ids — they never change. New personas come from POST /agency/personas, new creators join through an invite, new CRM accounts from POST /accounts.

3. Call the creator path#

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

# Create a drop on that persona
curl -X POST "https://www.dropfans.io/api/external/v1/creators/cmh4v2q8k0003xy9z7w6v5u4t/drops" \
  -H "Authorization: Bearer $AGENCY_API_KEY" \
  -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. GET /me returns key.via: agency (and the agency in key.managedBy) or app.

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

The X-Dropfans-Account header (deprecated)#

Sending X-Dropfans-Account: <account id> on the plain path does the same and keeps working. Responses to such calls carry Deprecation: true and a Link: <…/v1/creators/{id}/…>; rel="successor-version" header pointing at the path form. Sending both the path and a header that names another account is a 400 account_mismatch.

Permissions#

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

Your app owner’s key has every permission except co-performers on the accounts your app onboarded. Each reference page names the permission it needs. Requesting or cancelling a payout and changing payout methods are never possible for another account: those endpoints refuse a creator (creator_scope_not_allowed / account_header_not_allowed) and keys an agency minted for a managed account (agency_key_not_allowed), whatever the permissions.

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 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 for each creator 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.