Scopes
Scopes limit what an access token can do in Account Chief. Choose them when you create an access token. Start with the narrowest scope that covers your integration. The shared scopes guide explains parent scopes and write access.
Each endpoint in the REST API reference lists its required scope under security.
Available API scopes
Full access
| Scope | Access |
|---|---|
accountchief | Every Account Chief API operation |
Broad scopes
| Scope | Access |
|---|---|
accountchief:read | Read all Account Chief resources |
accountchief:write | Read and change all Account Chief resources |
Teams
| Scope | Access |
|---|---|
accountchief:team:read | List and view basic team information |
accountchief:team:write | List and view teams and update their name, Gravatar email, and timezone |
Connected applications
| Scope | Access |
|---|---|
accountchief:team:apps:read | List connected applications and view their plans, limits, and usage |
Invoices
| Scope | Access |
|---|---|
accountchief:team:invoices:read | List and view team invoices |
Members
| Scope | Access |
|---|---|
accountchief:team:members:read | List and view team members |
accountchief:team:members:write | List, view, invite, change the roles of, and remove team members |
Scopes do not override the authenticated user's team role. User credentials need the Owner role to invite someone, change another person's role, or remove someone else. Any team member can remove themselves. A team access token with this scope acts for its own team. See Manage teams and roles for the role permissions and ownership safeguards.
Team access tokens
| Scope | Access |
|---|---|
accountchief:team:tokens:read | List and view team access token metadata |
Team resources use separate branches
accountchief:team:write includes accountchief:team:read, but it does not grant access to connected applications, invoices, members, or token metadata. Request those scopes separately. accountchief:team:members:write includes the matching member read scope.
The team token endpoints return metadata such as a token's name, scopes, creator, and timestamps. They never return token values or hashes.
Choose identity scopes
| Scope | Access |
|---|---|
profile | Read the user's name, profile picture, and timezone as standard OpenID Connect claims |
email | Read the user's primary email address and verification state |
teams | Read the user's teams in identity responses and use the basic team list and detail endpoints |
Do not use an email address as the stable account identifier. OpenID Connect's sub claim identifies the user.
Request teams when the user needs to choose which team the integration should use. A team-scoped token limits the returned team information to its selected team. User credentials can use accountchief:team:read instead of teams for the basic team list and detail endpoints, but that API scope does not add team claims to identity responses.
Billing memberships are available from the Account Chief team endpoints, but Account Chief omits them from connected-app identity responses because Billing does not grant access to connected apps.
Keep the selected team ID with the connection. Product APIs may also accept that ID in a request header. For example, Domain Chief documents its behavior under Select a team.
Add OpenID Connect behavior
Add openid when you need an ID token or the OpenID Connect UserInfo endpoint. Add offline_access only when the application needs a refresh token for background access.
These protocol scopes change how authorization works, but they do not expose identity fields on their own. Combine openid with profile, email, or teams for the claims your application needs.
Use the OpenID Connect discovery document to find the current UserInfo and signing-key endpoints.
Personal access token defaults
Personal access tokens always include:
Code
Account Chief adds these defaults automatically, so they do not appear as optional checkboxes when you create a personal token. Team access tokens and OAuth access tokens only receive the scopes allowed by their own configuration and grant.
A team access token can always list and view its own team, including a legacy token without Account Chief scopes. Every other Account Chief API request needs its matching scope.
The OAuth token response contains the scopes actually granted. Store that value with the connection instead of assuming every requested scope was approved.
Common token setups
Manage team membership
Code
The token can list, invite, change the roles of, and remove team members when its credential also passes the team role rules above. It cannot update team settings or read invoices.
Build a billing report
Code
The token can read connected application plans and usage alongside team invoices. It cannot change team settings or membership.
Update team settings and membership
Code
Both scopes are required because team settings and members are separate resources.
Inventory team tokens
Code
The token can read token metadata for an accessible team. It cannot retrieve secrets, create tokens, or revoke them.
Continue from here
- Read How scopes work for parent scopes, read and write inheritance, and least-privilege examples.
- Follow OAuth and OpenID Connect to request a client and run the authorization code flow.
- Use Tokens for personal and team token creation, storage, rotation, and revocation.