Permissions and scopes

PilotFox has one permission vocabulary for people, API keys, share links and MCP tokens. A permission is written resource:action, such as analytics:read. In API requests and responses, a set of permissions is an object of resource → actions:

{ "analytics": ["read"], "goals": ["read", "write"], "ingest": ["write"] }

Every endpoint under /api/v1 requires one permission, listed at the end of this page, except a few public, account and instance-administration endpoints. PilotFox checks it against what the caller holds on the site or organization of the request.

Roles and permissionsCopy Anchor Link

People get permissions from their role in the organization. Each role holds everything the role before it holds, and more. An API key holds exactly the permissions it was created with: any of those its creator's role holds, plus, for a key created by an owner or an admin, the key-only ones.

organization:delete and a few more permissions of the roles (member:create, member:delete, invitation:create, invitation:cancel, team:create, team:delete, ac:*), as well as apiKey:update, are used by no /api/v1 endpoint: the dashboard manages the organization, its members, invitations and teams through /api/auth, which takes a signed-in session only. On an API key they grant nothing.

Restricted members. A member whose access is limited to some sites sees only the sites granted to them (directly or through a team), with the role of that grant (viewer, member or editor; the highest when several reach a site); across the organization they count as a viewer. A member who sees every site holds, on each site, the higher of their role and any grant they have there. Owners and admins always see every site.

Key-only permissionsCopy Anchor Link

Two permissions belong to no role. Only API keys can hold them, and only owners and admins can grant them:

Their endpoints refuse every other credential with 401, whatever it holds: a signed-in owner, a share link or an MCP token cannot call them.

Give these permissions to dedicated keys: an ingest key needs nothing else, and a key that records payments needs nothing but revenue:write.

Site restrictionsCopy Anchor Link

A key created with a list of sites (siteIds) reaches only those sites:

A key with a site list also gets 403 where an endpoint needs access to every site of the organization: saving, changing or deleting a segment or an annotation for the whole organization ("scope": "org"), and linking a Search Console property (see below).

Share links and public sitesCopy Anchor Link

Two kinds of caller read a site's data without belonging to its organization:

• Share links. A share link's token (x-share-token header or ?share=) holds the scopes chosen when the link was made: analytics:read (the default), and optionally sessions:read, users:read and replay:read. Its creator must hold every scope on the site. A share link only reads, and only endpoints marked share links below accept it.
• Public sites. A site whose settings make it public opens the endpoints marked public sites below to everyone for reading, with no credential needed: anyone gets analytics:read there, on top of what they already hold.

Neither can filter by the dimensions that need sessions:read unless a share link carries that scope.

Checks beyond the endpoint's permissionCopy Anchor Link

A few endpoints check more than the permission listed for them, and answer 403 when the check fails. Paths are relative to /api/v1:

• Creating an API key (POST /orgs/{orgId}/api-keys) needs a signed-in person: API keys and MCP tokens are refused.
• Starting a Search Console connection (POST /orgs/{orgId}/search-console/connect) needs a signed-in person: API keys and MCP tokens are refused.
• Linking a Search Console property (PUT /sites/{siteId}/search-console), and listing the connections and properties to link from (GET /sites/{siteId}/search-console/connections and …/properties), need access to every site of the organization: a member who sees every site, or an API key without a site list.
• Saving, changing or deleting a segment or an annotation for the whole organization ("scope": "org") needs access to every site of the organization, with segments:write or annotations:write in the member's own role (a site grant is not enough), or an API key without a site list. Through MCP, an annotation can be neither public nor for the whole organization.
• Creating a share link (POST /sites/{siteId}/share-links) needs every scope of the link on the site; MCP tokens are refused.
• Opening an affiliate's portal link (POST /sites/{siteId}/affiliates/{id}/share) also needs revenue:read; MCP tokens are refused.
• Pointing a Slack or Discord notification at a URL, or switching it on (PUT /sites/{siteId}/notifications/slack or …/discord) also needs revenue:read, since the webhook then receives every sale. The webhook keeps receiving sales only while the member or API key that set its URL still has revenue:read on the site; see Slack and Discord webhooks.
• Email report subscriptions (GET and PUT /sites/{siteId}/reports) belong to a person: a signed-in session or an MCP token acting for one; API keys are refused.
• Exporting raw events (GET /sites/{siteId}/export) also needs sessions:read.
• A payment's journey (GET /sites/{siteId}/payments/{paymentId}/journey) also needs sessions:read.
• Making a site public (PATCH /sites/{siteId} with settings.public: true), or creating one public (POST /orgs/{orgId}/sites with settings.public: true), also needs analytics:read; a refused creation creates nothing.
• Filtering by an identity dimension or another sessions-only dimension needs sessions:read (a 400); see Query parameters.
• MCP OAuth tokens act as their user: everywhere they hold the user's current permissions, limited to the scopes the user approved, in one organization. See MCP with OAuth.

Some answers also leave fields out for a caller without a second permission:

• Payments (GET /sites/{siteId}/payments): customer_email, session_id, visitor_id, user_id and credited_session_id are null without sessions:read.
• Affiliates (GET /sites/{siteId}/affiliates/stats and …/{id}/report): payments, revenue, commission and conversion_rate are null, and a report's recent_payments empty, without revenue:read.
• Annotations (GET /sites/{siteId}/annotations): without annotations:read, only the public annotations, with createdBy set to null.

Permission per endpointCopy Anchor Link

The tables below follow the sections of the API reference, and each endpoint links to its reference page. They are generated from the same OpenAPI document, which the API builds from each route's access rule, so they say exactly what the API enforces:

• Permission is what the caller must hold on the site (/api/v1/sites/{siteId}/…) or in the organization (/api/v1/orgs/{orgId}/…). A signed-in session or an API key holding it is accepted, unless the notes say otherwise.
• API keys limited to some sites are refused (403) on the organization endpoints, except where the notes say keys limited to some sites: their sites only.
• Share links and public sites mean those callers are accepted too (see above). Checked by the endpoint marks a public endpoint that reads a credential itself.
• Endpoints outside /api/v1 (the tracker's, the map tiles, MCP and the sign-in endpoints under /api/auth) need no permission; their notes say which credential they take. Each MCP tool needs the permission of the endpoint it calls.

Each GET under /api/v1 also answers HEAD with the same permission, except the export, the realtime stream and favicons.

SystemCopy Anchor Link

AccountCopy Anchor Link

OrganizationsCopy Anchor Link

API keysCopy Anchor Link

SitesCopy Anchor Link

Share linksCopy Anchor Link

AnalyticsCopy Anchor Link

EventsCopy Anchor Link

ErrorsCopy Anchor Link

GeographyCopy Anchor Link

LiveCopy Anchor Link

BotsCopy Anchor Link

PeopleCopy Anchor Link

SessionsCopy Anchor Link

GoalsCopy Anchor Link

FunnelsCopy Anchor Link

JourneysCopy Anchor Link

SegmentsCopy Anchor Link

AnnotationsCopy Anchor Link

ReplaysCopy Anchor Link

RevenueCopy Anchor Link

Payment providersCopy Anchor Link

AffiliatesCopy Anchor Link

Search ConsoleCopy Anchor Link

NotificationsCopy Anchor Link

ImportsCopy Anchor Link

ExportsCopy Anchor Link

IngestCopy Anchor Link

TrackerCopy Anchor Link

MCPCopy Anchor Link

AuthCopy Anchor Link

AdminCopy Anchor Link