Authentication

Every endpoint requires authentication. The public API uses a single scheme: an API key sent as a Bearer token.

Two kinds of key

A personal key acts as you: demoting or removing you narrows or cuts off your keys immediately. An organization key belongs to nobody, so there is no role to intersect with; its scopes are its whole authority, bounded once at issue time by what the person issuing held in that organization.

Rule of thumb: a personal key for things that should act as you (local scripts, exploration), an organization key for anything a team depends on (CI pipelines, cron jobs, long-running automation).

Creating a key

• Personal: Account → Access → Create key, or POST /account/api-keys.
• Organization: Organization settings → Access → Create key, or POST /organizations/{org_id}/api-keys. Needs org_key:manage, which members and owners hold and viewers do not; partner access never holds it.

Every key names three things:

• Scopes: the permissions the key holds, in resource:action form (release:write, analytics:read). At least one. The picker only offers what you hold yourself; "everything I hold" expands into the explicit list at creation time, so a key never gains a permission that ships later. No key can carry org_key:manage: a credential must not be able to mint credentials.
• Where it acts: a personal key lists at least one organization and never reaches one that was not on its list, even if you join more later. An organization key is bound to the organization it was created in. On a partner-plan organization, a key can instead be issued with audience: "clients": it acts in whatever organizations are your clients right now, resolved on every request and capped at the member bundle.
• Expiry: a date, or never. An expired key answers 401 credential_expired (distinct from a wrong key, so a pipeline log says what to do).

Creating a key asks for your password again and sends a security notification mail. The secret (fm_… or fmo_…) is shown once. Store it in your secret manager immediately; there is no recovery flow.

An application's CI/CD snippet in the dashboard creates a release:write key in place and writes it into the curl command; it asks whether the key should belong to you or to the organization. GET /permissions lists every permission with a description and the roles that hold it.

Sending it

Authorization: Bearer fm_abcdef…

curl https://api.fastmon.eu/sites \
  -H "Authorization: Bearer fm_abcdef…"

What a key can do

• A personal key: never more than its owner. On every request the key's scopes are intersected with your current role in that organization. Demoting or removing you narrows or cuts off your keys immediately.
• An organization key: exactly its scopes. There is no owner to follow, so nothing changes it after issue except an explicit edit. A clients key follows the partner relationship instead: an organization taken on later is included, one handed back drops out on the next request.
• Only where it was issued for. Resources in any other organization are hidden from it (404); the organization routes themselves answer 403 permission_denied. The two lists that key on the user rather than an organization (GET /organizations and the Ask conversations) are filtered to the key's organizations.
• Not for credential or account management. Creating, editing, rotating, or revoking keys, passkeys, 2FA, password, e-mail, account deletion, creating an organization, and accepting an invite need a dashboard session. So do the platform /admin routes.
• Missing scope: 403 permission_denied, with the missing permission in details.permission. See Errors.

GET /permissions/self reports what the calling key can actually do per organization next to the reach it was issued for. For a personal key, an organization you have since left shows up as the difference between the two.

Editing and rotating a key

A key's name, scopes, and expiry change in place with PATCH; the secret stays. Re-authentication is asked only when the edit hands the key more than it had: a scope it did not carry, or a later expiry. Narrowing and renaming pass without a factor.

Rotating (POST …/rotate) issues a successor with the same name, scopes, and reach and a fresh secret, then retires the old one: immediately by default, or after a grace window of up to 24 hours for the ordinary case where a deploy has to reach every consumer of the secret first. Rotating never extends the expiry.

For organization keys, both are gated on standing: only someone who holds everything the key holds may edit, rotate, or rename it. The list reports this per key as editable. Revoking is deliberately not gated this way; containment must not wait for an owner to be reachable.

Managing keys

Account → Access lists your personal keys; Organization settings → Access lists the organization's keys, next to its connected apps. Each key shows where it acts, its scopes grouped by resource, its expiry, its last use (last_used_at, updated at most every five minutes), and whether it can act right now. Revoking takes effect immediately and needs no re-authentication; on the organization list, anyone with org_key:manage may revoke any key. Revoked keys stay listed in their own section as the record that the key existed and when it was pulled; the API returns them with ?include_revoked=true.

Keys are hashed server-side; only the prefix is queryable.

Common surprises

• You can't manage another user's personal key. Even an owner can only see and revoke their own. A shared job that must survive people is what organization keys are for. Every organization a key names records its creation, changes, and revocation in its audit log.
• Registration hands out no key. A key needs an organization to be bound to; create it once your organization exists.
• Connected apps don't hold keys anymore. A first-party integration authorized via OAuth holds a connection with short-lived tokens of its own; see OAuth apps. The key kind those connections used to end in is gone, so there are exactly two kinds left, personal and org, and a key entry no longer carries an oauth_client_id. Read connections at /account/connections and under the organization's connections instead.

Related

• API overview: base URL and conventions.
• OAuth apps: how first-party integrations connect without a key.
• Organizations → Roles: the role bundles keys are cut from.
• Errors: 401 and 403 responses.