Authorization and scopes

The Picked API controls access with scopes. Every authenticated caller carries a set of scopes, and those scopes decide which operations the caller can do. A caller is either a user with a session or an API key. This guide covers the scopes, the roles, and how the API resolves a permission.

The format of a scope name

A scope has the form resource/action:

organization/read
organization_members/create
organization_projects/delete

• resource — a lowercase name. It uses an underscore between words, as in organization_members and organization_api_keys.
• action — one of create, read, update, or delete.

The GraphQL schema holds the scopes in the Scope enum. There they are uppercase with an underscore between words, as in ORGANIZATION_READ and ORGANIZATION_MEMBERS_CREATE. The two forms name the same scope.

Full scope list

These are the scopes:

Organization

Organization members

Organization invitations

Organization projects

A scope on content inside a project also gives organization_projects/read. The workspace, integration, lead, action run, and report scopes all give it. They do not give organization_projects/create, organization_projects/update, or organization_projects/delete.

Organization API keys

Organization integrations

Organization reports

Roles

Each member of an organization holds one of two roles:

Owner

An owner has full control inside the organization. These are the default scopes of an owner:

• All organization/* scopes (read, update, delete)
• All organization_members/* scopes
• All organization_invitations/* scopes
• organization_projects/read, organization_projects/update, organization_projects/delete
• All organization_api_keys/* scopes
• All organization_integrations/* scopes
• organization_reports/read

Member

A member can reach most things, but cannot delete the organization and cannot control another member. These are the default scopes of a member:

• organization/read, organization/update
• organization_members/read
• organization_invitations/read
• organization_projects/read, organization_projects/update, organization_projects/delete
• All organization_api_keys/* scopes
• All organization_integrations/* scopes
• organization_reports/read

These are the differences between an owner and a member:

How scopes are resolved

When an authenticated request reaches the API, the API resolves the scopes like this:

1. A user with a session — the API finds the role of that caller in the target organization. It then gives the caller the default scopes of that role.
2. A request with an API key — the API uses the scopes that the key received when somebody created it. Those scopes are always scopes of the user who created the key.

Most queries and mutations point at one organization. For those, the caller must hold the scope inside that organization. For a root-level operation such as organizationCreate, the API resolves the scope at the account level.

When the caller does not hold the scope that an operation needs, the API returns an authorization error with the code FORBIDDEN. See Errors.

Operations and required scopes

This table gives the scope that each common operation needs:

Queries

Mutations

Some mutations do not require organization-level scopes because they operate on the caller's own data:

userMfaReset needs the root-level scope users/reset_mfa (USERS_RESET_MFA). The mutation removes every authenticator of a user and signs the user out everywhere, so their next sign-in starts at the setup.

Read your scopes

Root-level scopes

The viewerScopes query returns the root-level scopes for the authenticated caller:

query {
  viewerScopes
}

Response:

{
  "data": {
    "viewerScopes": ["ORGANIZATION_CREATE"]
  }
}

Organization-level scopes

Each Organization object exposes a viewerScopes field that returns the scopes the caller has within that specific organization:

query {
  organization(input: { slug: "my-company" }) {
    id
    name
    viewerScopes
  }
}

Response:

{
  "data": {
    "organization": {
      "id": "org_abc123",
      "name": "My Company",
      "viewerScopes": [
        "ORGANIZATION_READ",
        "ORGANIZATION_UPDATE",
        "ORGANIZATION_MEMBERS_READ",
        "ORGANIZATION_PROJECTS_READ",
        "ORGANIZATION_PROJECTS_UPDATE",
        "ORGANIZATION_PROJECTS_DELETE",
        "ORGANIZATION_API_KEYS_CREATE",
        "ORGANIZATION_API_KEYS_READ",
        "ORGANIZATION_API_KEYS_DELETE",
        "ORGANIZATION_INTEGRATIONS_CREATE",
        "ORGANIZATION_INTEGRATIONS_READ",
        "ORGANIZATION_INTEGRATIONS_UPDATE",
        "ORGANIZATION_INTEGRATIONS_DELETE",
        "ORGANIZATION_REPORTS_READ"
      ]
    }
  }
}

Use this to build a UI that changes with the permissions of the caller. An example is a Delete Organization button that the UI hides when the caller does not hold ORGANIZATION_DELETE.

Related

• Authentication
• How to authenticate with an API key
• API keys — the dashboard surface.