Keys and scopes

Every key has a tier and a set of scopes. The tier decides who can create it; the scopes decide what it can do.

Key tiers

Every key has a tier. The tier decides who can create it, whether it needs X-Tenant-ID, and its default rate limit.

TierWho creates itUsed forDefault limit
orgAn organization Admin or Scheduler, in Settings → API Keys.One organization's integrations.120 requests per minute
userA signed-in user, in Settings → AI Tools (AI Connectors).Acting for one provider, client or consumer in their own portal.60 requests per minute
platformFido platform administrators only.Fido's own cross-organization tools. Customers do not get these.300 requests per minute

Organization and user keys work only for the organization they were created in. Sending one with a different X-Tenant-ID is rejected.

Scopes

A scope is module:action. The modules and actions are the same ones you set for a role in Settings → Roles & Permissions.

ActionNeeded by
readGET requests
writePOST requests
editPUT and PATCH requests
deleteDELETE requests

An endpoint's own permission rule can ask for a different action. The reference shows the exact scope each endpoint needs.

  • Wildcards work: * (everything), assignments:* (every action in one module), and *:read (one action in every module).
  • Scopes do not imply each other. assignments:write does not let a key read. Add assignments:read as well.
  • A key's scopes narrow what it can do. The key owner's role must also allow the action. A missing scope returns 403 and names the scope.
  • /v1/whoami needs no scope.

The modules a key can be scoped to in the published API:

assignments, check_ins, clients, consumers, finance, forms, handshakes, history_logs, providers, requests, schedule, settings_assignments_shifts, settings_broadcast_dispatch, settings_general, settings_locations, settings_notifications_preferences, settings_preferred_users, settings_rates_billing, settings_restricted_users, settings_service_setup, shifts, team

check_ins covers provider sign-in and sign-out records. check_ins:read is the scope for GET /v1/check-ins. requests covers the client, consumer and provider request inboxes. The scope list in the key dialog only offers scopes your role can use.