Scopes and permissions

What a Competitor Tracker & Co. credential can do: the scope catalog, the three organization roles and how scope and role combine to authorize each request.

Two things decide whether a call to /v1/* is allowed: the scope on the credential and the role of the member behind it. Both must pass. This page is the one place that defines them; the OAuth2 and API key pages point here.

Scope and role answer different questions. Scope says what this credential may ask for — it rides on the token or key. Role says what this person may do — it comes from their membership in the organization. A read token can never write; a write-scoped token held by a member still cannot run an admin operation.

Scopes

A credential carries a set of scopes. A request is refused when the credential lacks the scope the endpoint needs: a read endpoint wants the matching :read scope, a write endpoint the matching :write. The required scope for each endpoint shows up on its page in the API reference, on the "Required scope" line.

Scope	Grants
`openid`	Sign-in. Issues an `id_token`.
`email`	Puts the user's email on the `id_token`.
`profile`	Puts the user's name on the `id_token`.
`mcp`	Lets an MCP client act on the user's behalf.

Tracked data

Scope	Grants
`competitors:read`	Read the competitors you track.
`competitors:write`	Add, change and remove tracked competitors.
`labels:read`	Read labels.
`labels:write`	Create, change and delete labels.
`snapshots:read`	Read snapshots.
`pages:read`	Read tracked pages.
`changes:read`	Read detected changes.

Your account

Scope	Grants
`account:read`	Read your own profile and account settings.
`account:write`	Update your own profile and account settings.
`billing:read`	Read the coin balance and transaction history.

Organization administration

Scope	Grants
`org:read`	Read organization settings.
`org:write`	Manage organization settings: rename, ownership, deletion.
`members:read`	Read members.
`members:write`	Manage member roles.
`invites:read`	Read invitations.
`invites:write`	Create and revoke invitations.
`dispatches:read`	Read dispatch settings and delivery history.
`dispatches:write`	Manage notifications, recipients and webhooks.

When you mint an API key, you can only grant scopes within your own role's reach. A member can grant the tracked-data scopes, their own account scopes and the read-only organization scopes. The administration write scopes — org:write, members:read, members:write, invites:read, invites:write and dispatches:write — are yours to grant only as an admin or owner. Ask for a scope above your role and the request comes back refused. Grant the narrowest set the job needs.

Roles

Every /v1/* endpoint declares a required organization role. The role is read from the caller's membership for the org bound to the credential. There are three:

Role	Can do
`member`	Day-to-day work on the organization's tracked data.
`admin`	Everything a member can, plus operations that change organization configuration or destructively affect shared resources.
`owner`	Everything an admin can, plus organization-lifecycle operations: transferring ownership and deleting the organization. An owner must transfer ownership before leaving.

Roles are hierarchical: owner ⊃ admin ⊃ member. An endpoint that requires admin admits an owner too. An endpoint that requires member admits all three. The required role for each endpoint shows up on its page in the API reference, on the "Required role" line.

The owner role is granted in exactly two ways. When you first sign up you become the owner of your personal organization. After that, the only path to a different owner is POST /v1/org/transfer-ownership, which atomically demotes the current owner to admin and promotes the named target. There is no admin-to-owner promotion.

When a check fails

A missing scope returns 403 with code: "InsufficientScope". A role that's too low returns 403 with code: "InsufficientRole". Both carry a resolution string with the next step: grant the credential the scope it needs, or ask an organization admin for a higher role.