Skip to main content
HQ uses a resource:action scope vocabulary. A personal access token or OAuth client is granted a set of these, and each endpoint lists the scope it requires under its Authorizations.

​
The vocabulary

​
How scopes resolve

  • A token never exceeds its user’s role. The effective permissions are the user’s role capabilities intersected with the token’s granted scopes. A non-admin’s token that asks for admin is silently clamped — never escalated.
  • admin is role-gated. Only a user with the admin role can hold it. An admin token can do everything a member token can, plus workspace administration.
  • Request least privilege. Ask only for the scopes you use. For OAuth, the granted set is your request intersected with the client’s allowed scopes; requesting only scopes the client isn’t allowed yields invalid_scope.
  • Unknown scopes are ignored (forward-compatible) — a scope added later won’t break an existing token.
Legacy coarse tiers still work: user (or integrator) grants every non-admin scope; admin grants everything. New integrations should use the explicit resource:action scopes above.