How to rotate a DigitalOcean API token

Generate a new personal access token with the same scopes on the Tokens tab of the control panel, switch your scripts and tools to it, and delete the old token once nothing uses it. Each token stands on its own, so the old and the new one work side by side during the switch. Deleting a token revokes its access (DigitalOcean docs). The token menu also offers Regenerate, but the documentation doesn't say what happens to the old value, so don't count on it for an overlap.

Crunu doesn't generate, regenerate or delete DigitalOcean tokens; it has no DigitalOcean integration. It works out which DigitalOcean values a departing person received, keeps the new token as a new environment version, and passes it to the tools that call the API.

Scopes age differently

How a token behaves over time depends on the scope you gave it, and this is a good reason to look at it again during a reissue:

• Full Access uses the api:write alias and grants everything your team role allows. If the role gains permissions, so does the token.
• Custom Scopes keeps exactly the scopes chosen at creation. A later change to your role adds nothing to the token.
• Read Only uses the api:read alias and reads everything your role can read.

You can't edit a token's scope after creation, and a request outside its scopes gets 403 Forbidden. If a team owner narrows your role, existing tokens lose those permissions too. In practice, an old Full Access token quietly grows with its owner's role, so replacing it with a custom-scoped token is often the main gain of the reissue. It also pays to note whose token it is: its permissions come from the team role of the person who created it, so a token that serves the whole team shouldn't depend on one person's role.

Prefixes and leaked tokens

DigitalOcean tokens start with a prefix that names their type: dop_v1_ for personal access tokens made in the control panel, doo_v1_ for tokens issued to applications through OAuth, and dor_v1_ for OAuth refresh tokens (API reference). The prefixed format came with DigitalOcean's 2022 token update, which also joined GitHub's secret scanning program: a token exposed publicly is revoked automatically and its owner is notified (DigitalOcean blog). A token without the prefix predates that update, and DigitalOcean recommended regenerating such tokens at the time.

Reissue without downtime

crunu run --env data-pipeline/production -- sh -c \
  'curl -s https://api.digitalocean.com/v2/account -H "Authorization: Bearer $DIGITALOCEAN_TOKEN"'

A token with custom scopes may not be allowed to read the account. If it gets 403 Forbidden, test with a request inside its scopes instead.

When someone leaves the team

DigitalOcean is direct about the limits of removing a team member. Removal revokes their access to the team in the control panel and the API. It doesn't revoke their access to Droplets through SSH keys or other credentials, because DigitalOcean doesn't manage what's inside a Droplet after it's created (team limits). A full offboarding therefore has three parts:

• remove the person from the team;
• reissue every DigitalOcean token they could read, such as a shared CI token, and move automation that ran on a token they created to a new one;
• remove their SSH keys and other credentials from the Droplets themselves. Rotating SSH keys covers that part.

In Crunu, removing the person produces a reissue checklist of the values they received, with a link to the DigitalOcean token page for recognized values. Leaks follow the same steps, faster: delete the token first, then deploy the replacement. What to rotate when a developer leaves gives the full order of work, and the offboarding checklist builds the list for your stack.