Getting started

API Keys

Create, scope, rotate, and revoke API keys for the FansMetric Public API. Keys are minted from the FansMetric web app and are scoped to an organization — every key in the same org shares the same permissions surface and the same rate-limit windows.

Current plan

Heads up — the raw API key is shown to you exactly once, right after it's generated. Copy it before closing the dialog. After that it can't be retrieved; if you lose it, revoke the key and create a new one.

Before you start

API keys are created from inside the FansMetric web app, under Public API → API Keys. Make sure your account meets the requirements below — if you don't see the Public API section in the sidebar, one of these checks is failing.

You're an organization admin. Team members without admin rights can use keys, but only admins can mint, edit, or revoke them.
Your FansMetric organization is enabled for the Public API. The platform is rolled out per-organization in production; if you're not seeing the menu, reach out to your account contact and we'll flip it on.
Your organization has at least one connected OnlyFans account in the connected state — otherwise the key will authenticate but every account-scoped endpoint will 404.

Generate a key

Open Public API → API Keys and click Create API Key. The dialog asks for two things — a name and a set of roles. Both can be set later for the roles, but the name is permanent.

Name — a human label so you can identify the key in the dashboard later. Up to 100 characters, unique among your organization's active keys (case-insensitive), and immutable once set. Pick something descriptive like Production, Staging, or Analytics Bot.
Roles — one or more API roles that define what this key can do. You can leave this empty at creation and assign roles later via Edit roles, but a key with no roles will return 403 on every endpoint.
Click Create Key. The new key appears in a green banner at the top of the page — copy it now. After you navigate away, the raw value is unrecoverable; the only way to get a fresh secret is to revoke the key and create a new one.

Key format

Every key begins with the literal prefix fm_api_ followed by a random string. The dashboard only stores the first 20 characters as a display prefix — the rest is never written to disk, which is why we can't show the full key to you again after creation.

The dashboard lists each key by its prefix (for example fm_api_aGVsbG9...) followed by an ellipsis. Use the prefix to tell two active keys apart at a glance.
Treat the full key as a password. It carries every permission attached to its roles, so anyone who sees it can act as your organization until the key is revoked.

Use the key in requests

Send the raw key on every authenticated request in one of two headers. Either form works — the bearer form is the recommended default for tooling that already understands OAuth-style headers; the X-API-Key form is convenient for environments where setting Authorization is awkward.

Authorization: Bearer fm_api_...
X-API-Key: fm_api_...
Never put the key in a query string. FansMetric only reads keys from headers, and putting secrets on the URL leaks them into access logs.
See Auth for the full request envelope, error codes, and rate-limit response headers.

Roles and permissions

Permissions are per-route. The Public API ships with one permission per endpoint — for example api_chats_list, api_messages_send, api_tracking_links_create. A key's effective permissions are the union of every permission attached to every role assigned to it.

Roles are managed under Public API → Roles. Each role has a name, an optional description, a color, and a set of permission keys. The names must be unique within your organization.

Every organization starts with a built-in Admin role that grants every Public API permission. That role is identified internally by an is_default flag — you can rename it to suit your taste, but it can't be deleted, and it'll always be the role assigned when nothing else fits.

Assign multiple roles to one key — permissions stack via union.
Editing roles on an existing key doesn't rotate the secret. Use Edit roles on an active key to change scope without re-issuing.
Roles cannot be deleted while any active key references them — revoke or reassign the keys first.

Active-key limit

An organization can hold up to 10 active keys at a time. Revoked and expired keys don't count toward the cap. When you reach the limit the Create API Key button is disabled and the page shows a warning — revoke or expire an existing key to free up a slot.

Keep the active surface small. Every active key is a potential leak, and the per-org rate-limit window is shared across all of them.

Rotate a key

Rotation is two steps in this order: create the replacement first, then revoke the old one. Don't revoke first — there's no overlap window, and any caller still holding the old key will start failing immediately.

Create the new key with the same role set as the one you're replacing.
Roll the new secret out to every caller (env vars, secret manager, CI variables) and confirm requests are succeeding against it.
Revoke the old key. Revocation is immediate — the next request bearing the revoked key returns 401.
Rotate on a schedule that matches your security posture. Always rotate immediately on team changes, on suspected leak, or after any incident involving the machine that held the key.

Revoke and unrevoke

Revoking a key takes effect immediately — the API stops accepting it on the next request. Revocation is reversible from the Inactive tab as long as the key hasn't passed any expiry date and your organization isn't already at the 10-key active cap.

Revoke surfaces the key in the Inactive tab with the timestamp of the revocation. The key's name is still reserved while it's revoked, but only against other active keys — you can create a new active key with the same name as a revoked one.
Unrevoking restores the key in place. It fails if the key is past its expiry date, or if the org would exceed the active-key cap.
If you accidentally revoke and can't unrevoke, just create a new key.

Last-used tracking

Every successful authenticated request updates the key's last_used_at timestamp. The dashboard shows this column so you can spot keys that have gone dark — those are usually safe to revoke. A blank Last used means the key has never been used to authenticate a successful request.

Errors specific to API keys

Auth-related failures are returned as a flat { "error": "..." } body. The HTTP status tells you what failed:

401 — the key is missing, invalid, revoked, or expired. 401 responses do not consume a credit.
403 — the key authenticated successfully, but the role(s) attached to it don't include the permission required for the endpoint. Check the endpoint's reference page for the exact api_… permission slug it needs.
402 — the key is valid but your FansMetric organization has no active subscription. Repair billing inside the FansMetric app, then retry.

Rate limits

Limits are enforced per organization, not per key. Every key in the same org shares the same per-minute window (default 1,000) and the same per-day window (default 50,000). Adding more keys does not give you more throughput — it just spreads the same budget across more callers.

Headroom is reported on every successful response inside _meta._rate_limits (remaining_minute, remaining_day). When you hit either window you get 429, which also does not consume a credit.

Storing keys securely

Treat the raw key the same way you'd treat a database password.

Store the key in an environment variable or a secret manager (1Password, Doppler, AWS Secrets Manager, Vercel env vars) — never commit it to a repo.
If you ever push a key to git, revoke it immediately and rotate. Removing it from history is not enough.
Use separate keys per environment (Production, Staging, CI) so you can rotate one without disrupting the others, and so the dashboard's Last used column reflects something meaningful.
Restrict the role on each key to the minimum permissions it actually needs. A read-only analytics bot should not be holding a key that can api_messages_send.

Next steps

Once you have a key in hand, list the connected accounts your organization owns to confirm auth, scoping, and rate-limit headroom in a single call — see Quickstart and Get Accounts under the API Reference.

Getting Started

API Reference