Copy page

API

Scopes

Scopes limit what an access token can do. Choose them when you create an access token. The general scopes guide explains how Chief Tools applies scopes across its APIs.

Each endpoint in the API playground lists its required scope under security.

Available scopes

Full access

Broad scopes

Domains

Contacts

Events

DNS records

ACME

Redirects

Activity

TLDs

Every Domain Chief token can list and view TLDs and their indicative pricing, whatever its scopes. Older tokens may still include domainchief:tlds:read, which keeps working but is no longer needed.

Restrict a token to specific domains

Scopes decide what a token can do. You can also decide which domains and contacts it can do that for. Select Only selected resources under Domain Chief when you create the token, then list the domain names and contact handles, one per line.

A restricted token:

• Only reaches the listed domains. Other domains of the team return 404, as if they do not exist, and domain lists, the activity feed, and the team event feed leave them out.
• Can register or transfer in a listed domain name. Domain names do not have to exist yet, so you can create the token before registering the domain. Registering any other name returns 403 with code token.resource_not_allowed.
• Reads the contacts of the listed domains and the listed contacts, when its scopes allow reading contacts.
• Only changes or deletes listed contacts, because a contact can be shared by domains the token cannot reach. It cannot create contacts. Both return 403 with code token.resource_not_allowed.
• Publishes ACME challenges on the most specific listed domain that matches the challenge name.

For example, a token for Certbot that only issues certificates for example.com:

Code
Scopes:    domainchief:acme:write
Domains:   example.com

You can link to a prefilled token form with the resources query parameter, for example https://account.chief.app/team/select/token/create?scopes=domainchief:acme:write&resources[domainchief:domain]=example.com. Separate multiple domains with commas.

Common token setups

Start with the narrowest scopes that cover the integration.

Manage DNS records

Code
domainchief:dns:write

The token can read and change DNS records. It cannot list domains, manage contacts, or run domain lifecycle operations. The Terraform guide lists the scopes the Terraform provider needs.

Issue certificates with DNS-01 validation

Code
domainchief:acme:write

The token can only publish and delete TXT records on _acme-challenge names through the ACME endpoints. It cannot list domains, read DNS records, or change any other record. Use this scope for ACME clients such as Certbot and cert-manager. The DNS-01 guide explains how to set them up.

Read data for monitoring

Code
domainchief:read

The token can read domains, contacts, events, DNS records, redirects, TLDs, and activity. It cannot change them.

Keep a local copy in sync

Code
domainchief:events:read
domainchief:domains:read
domainchief:contacts:read
domainchief:dns:read
domainchief:redirects_web:read
domainchief:redirects_mail:read

The token can read the team event feed and retrieve current domains, contacts, DNS records, web redirects, and mail forwards. It cannot change those resources. Remove scopes for resource types the integration does not store. The data synchronization guide explains the snapshot and cursor workflow.

Check domain availability

Code
domainchief:domains:read:availability

The token can check availability. It cannot list domains or retrieve an existing domain.

Manage existing domains

Code
domainchief:domains:write, domainchief:dns:write, domainchief:contacts:write

The token can update existing domains, DNS records, and contacts. It cannot register domains, manage transfers, or delete domains immediately.