Copy page

API

Scopes

Scopes define what an OAuth client or API token is allowed to access across Chief Tools. Some scopes are shared OAuth scopes managed by Account Chief, while others are product-specific scopes for tools like Domain Chief and Tny.

Scope Families

Account Scopes

Scope	Description
profile	See your name and profile picture
email	See your primary email address
teams	List the teams authorized for the current token

App Scopes

App scopes follow a hierarchical format using colons as separators:

Code
{app}:{resource}:{action}

For example:

• domainchief - full access to Domain Chief
• domainchief:domains:read - read-only access to domains in Domain Chief
• domainchief:dns:write - create, update, and delete DNS records

App specific scope documentation:

• Account Chief API Scopes
• Domain Chief API Scopes
• Tny API Scopes

OAuth Scopes

These scopes are not tied to a single Chief Tool:

Scope	Description
openid	Request OpenID Connect authentication so the client can receive an ID token
offline_access	Allow the client to keep access without requiring you to sign in again

How App Scope Resolution Works

App scopes are resolved hierarchically. A broader scope automatically grants access to all more specific scopes beneath it. This means you don't need to list every individual scope - a single parent scope covers all its children.

Parent Scopes

A parent scope grants access to all its children:

Token has	Grants access to
domainchief	Everything in Domain Chief
domainchief:domains	All domain operations (read, write, register, transfer)
domainchief:domains:read	Read-only domain access

Write Implies Read

A :write scope at any level also grants :read access at the same level:

Token has	Also grants
domainchief:write	domainchief:read
domainchief:domains:write	domainchief:domains:read
domainchief:dns:write	domainchief:dns:read

Cross-Cutting Scopes

An action scope at the application level applies across all resources:

Token has	Grants access to
domainchief:read	domainchief:domains:read, domainchief:contacts:read, domainchief:dns:read, etc.
domainchief:write	All :write and :read scopes across all resources

Best Practices

• Principle of least privilege - only grant the scopes your integration actually needs. A DNS automation script should use domainchief:dns:write, not domainchief.
• Use expiring tokens - combine scopes with token expiration for temporary access.
• Separate tokens per integration - create dedicated tokens for each integration so you can revoke access independently.
• Only request offline_access when needed - ask for refresh-token access only when your client needs to keep working after the user is no longer present.