Organizations
The top-level account container. Everything in fastmon belongs to one.
An organization is the top-level container in fastmon. Every site, member, invite, and notification rule belongs to exactly one organization; nothing crosses that line.
Why it matters
Organizations are how fastmon keeps customers apart, how billing and plans hang together, and how access control is scoped.
Most accounts only ever have one organization. Multiple is mostly a thing for agencies and partners; see the partner plan below.
When you'd touch it
- First-time setup. The "create your account" flow makes one for you.
- Adding teammates. Invite by email, give them a role.
- Buying a plan. Plans live on the organization, not the user.
- DPA or invoice request. The organization is the legal counterparty.
- Compliance review. "Who can see this data?" is answered at the organization level.
What's on an organization
| Field | Type | Notes |
|---|---|---|
id | UUID v7 | Stable identifier. Used in API URLs (/organizations/{id}/…). |
name | string | Human-readable. Shows in the org switcher. |
plan | enum | none, beta, light, standard, partner, or enterprise. |
members | list of { user_id, role } | Roles: owner, member, viewer. The payload also carries your own role and permissions. |
Plans
| Plan | When you'd be on it |
|---|---|
none | The starting state. Nobody has chosen anything yet. |
beta | Early access during onboarding. Limited quota. |
light | Single-product teams. Default retention. |
standard | Production teams. Higher retention. |
partner | Agencies. Manage partner clients (sub-organizations you operate on behalf of someone else). |
enterprise | Custom limits, custom retention, signed DPA. |
A new organization starts on none and leaves it by exactly three routes: an approval starts its trial, a checkout buys a plan, or a partner provisions it.
The plan gates features and quotas. Which Web Vitals get collected isn't tied to the plan; every plan collects the same metrics.
What a plan is measured in. The billed unit is the application, and only a production application takes a slot: a development application is free and unlimited. A plan includes a number of production slots and a monthly pageview volume; both can be extended with permanent add-ons, bought in advance rather than billed after a spike. Creating or promoting a production application past the included slots is refused with 402 app_limit_reached (see Errors), and an organization with no entitlement at all gets 402 billing_required or 402 trial_expired.
Roles
A role is a fixed bundle of permissions. A permission is one capability in resource:action form (analytics:read, release:write, member:manage); every API route names the one it needs, and the dashboard shows or hides actions by the same list. GET /permissions lists every permission with a description and the roles that hold it.
| Role | Can do |
|---|---|
owner | Everything a member can, plus: organization settings (name, AI and synthetic monitoring consent), members and their roles, notification rules, the audit log, paying (billing:manage), transfer, and deletion. |
member | Everyday work: create and change sites, applications, releases, and synthetic pages; start synthetic runs; ask the AI assistant; invite people; read the invoices (billing:read); on a partner organization, manage its clients (partner:manage). |
viewer | Read-only. Sees dashboards, analytics, releases, synthetic results, notification rules, and the member list. Changes nothing, triggers nothing that costs money or sends mail, and does not see billing. |
Billing is two permissions, not one role. billing:read opens the invoices, the billing address, and the VAT id; billing:manage moves the money. Reading is a member permission and deliberately outside the viewer bundle, so a read-only seat does not see the Billing tab at all rather than opening it onto a row of 403s. Paying stays with the owner. An agency reading its client's invoices resolves to member there, which is exactly billing:read without billing:manage.
The bundles nest: a member holds everything a viewer holds, an owner everything a member holds. Personal API keys are cut from the same bundles: a key's scopes are permissions, intersected with your current role on every request. An organization key belongs to the organization instead and stands on its scopes alone, capped at issue time. Managing organization keys and connected apps takes org_key:manage, which members and owners hold and viewers do not.
An organization can have several owners. Owners change roles under Members (PATCH /members/{member_id}); only an owner can hand out the owner role. The last owner cannot be demoted or leave while other members remain (last_owner). Transfer ownership hands the organization to another member in one step.
Common scenarios
One product, one org
The default. One organization, one billing relationship, several sites under it (acme-marketing, acme-app, acme-docs).
Multiple unrelated products
Run two unrelated brands and want billing and access cleanly separated? Create two organizations. You can be a member of both.
Agency running client sites
Use the partner plan. Each client is a partner client: a sub-organization the agency runs. Agency users see all clients; the client sees only itself. A partner organization can also issue one API key that follows its client list instead of one key per client.
Any member of the partner organization can create a client, hand it to the customer with owner_email, and detach one again; on the other side, a member of the client organization can revoke the agency's access. What guards those routes is direct membership: an agency reaching an organization through a partnership can neither manage that organization's own clients nor revoke a partner link there.
Common surprises
- The org switcher is just UI. API requests scope by the URL (
/organizations/{id}/…), not by whichever tab you've got open. - Members are global fastmon users. Invite an existing user and the existing account gets reused; no duplicate.
- Adding a member directly needs an owner.
POST /organizations/{id}/membersrequiresmember:manage. Members invite instead, and an invite carries the role. - Sites can't move between organizations. If you genuinely need this, ping support. No self-serve action for it.
Related
- Sites: the resources owned by an organization.
- API: Organizations endpoints: programmatic access.