Create and rotate project API tokens safely

Project-scoped tokens let you automate work against a single documentation project without exposing broader workspace access. In Doxbrix, these are managed in Project API Tokens.

This guide explains how to create tokens responsibly, choose scopes, use expiries well, and rotate or revoke tokens without disrupting critical workflows.

Who this is for

• teams using the CLI in CI or deployment workflows
• teams building project-scoped internal integrations
• project admins responsible for operational security

What Project API Tokens are for

In Project settings → API Tokens, Doxbrix exposes Project API Tokens that are scoped to one project only.

They are intended for:

• authenticating the dxb CLI against a single project
• project-specific API integrations
• controlled automation where workspace-wide credentials would be too broad

Understand the available scopes

When you create a token, you can assign one or more scopes from the token form:

• Read docs
• Write docs
• Read project
• Admin project
• Use AI
• Run agents
• Read analytics

These scopes define what the token is allowed to do within the project.

Step 1 — Name the token clearly

In Create a token, start with Name.

Use a name that explains:

• where the token is used
• who owns the integration
• whether the token is temporary or long-lived

Good examples:

• CI pipeline
• Nightly quality audit
• Support reporting sync

Avoid vague names such as:

• token-1
• automation
• project key

Clear names make revocation and audits much easier later.

Step 2 — Choose the minimum required scopes

Next, set Scopes.

Choose only the permissions the integration truly needs.

Common patterns:

• content synchronization tool: Read docs, Write docs, Read project
• reporting job: Read docs, Read analytics
• project automation with settings changes: Admin project only when necessary
• AI-assisted tooling: add Use AI only if the integration actually invokes AI features

Step 3 — Set an Expiry whenever possible

Use Expiry to limit how long a token stays valid.

Available options include:

• No expiry
• 30 days
• 90 days
• 180 days
• 1 year

Recommended practice:

• use an expiry for temporary work
• use shorter expiries for experiments or new integrations
• use longer expiries only for stable, owned automation

Choose No expiry only when the operational tradeoff is deliberate and the token has strong ownership and rotation discipline.

Step 4 — Generate the token and capture it securely

After setting Name, Scopes, and Expiry, click Generate token.

When Doxbrix reveals the new token:

• copy it immediately
• store it in your approved secret manager
• record where it will be used

The full token value is shown once.

Step 5 — Verify the token in the target workflow

Before you consider setup complete, test the token in the system that will use it.

Confirm:

• authentication succeeds
• the token can perform the expected actions
• the token cannot perform actions outside its intended scope

If a workflow fails, do not immediately create a broader token. First confirm that the integration really needs additional scopes.

Step 6 — Review the Active tokens list

The Active tokens area shows token summaries including:

• token name
• key prefix
• scopes
• created date
• last used date
• expiry date

Use this list regularly to answer:

• which tokens are still active?
• which integrations have not been used recently?
• which tokens are close to expiry?
• are there tokens with scopes that are broader than current needs?

Step 7 — Rotate tokens intentionally

Rotation should be a normal operational process, not an emergency-only task.

Use this sequence:

1. create a replacement token with the correct scopes
2. update the target integration or secret store
3. confirm the new token is working
4. revoke the old token

This reduces downtime and prevents teams from keeping outdated tokens active “just in case.”

Step 8 — Revoke tokens immediately when risk changes

Use Revoke when:

• an integration is retired
• a token was stored insecurely
• an owner leaves the team
• a token has broader access than intended
• you finish a temporary migration or launch workflow

Revocation takes effect immediately, so confirm downstream ownership before revoking a token that may still be in production use.

A good token hygiene policy

For most teams:

• every token has a clear owner
• every token has a meaningful name
• scopes are minimal
• temporary workflows use expiry dates
• unused tokens are revoked
• rotation is part of routine operations

Related pages