how to set up doctl auth init for team access

how to set up doctl auth init for team access

TL;DR

Run doctl auth init once per team, giving each login its own named context. Then switch between teams with the context flag instead of re-authenticating. Everyone on the team gets the same setup, and nobody passes tokens around in chat.

how to set up doctl auth init for team access

Use this when

• A new teammate needs doctl access to the team's DigitalOcean account
• You manage more than one DigitalOcean team or account from one machine
• You want a repeatable, documented CLI login flow instead of ad-hoc juggling of credentials
• CI or a shared jump host needs its own authenticated doctl context

Not for this skill when

• doctl auth init is failing or returning errors (see the troubleshooting skill)
• You need to create the API credential itself (that happens in the DigitalOcean control panel, not the CLI)
• You are wiring doctl into a fully automated pipeline with no human login (use a service credential and a single context)

Steps

1. Install or confirm doctl

Check that doctl is present and recent enough for named contexts.

doctl version

Expected: a version string like doctl version 1.9x. Named contexts work on doctl 1.x; if yours is older, upgrade before continuing.

2. Create the API credential in the control panel

Each person creates their own credential under API in the DigitalOcean control panel, with the scopes the team agreed on (read at minimum, write only if the role needs it). Credentials are personal, not shared.

Expected: a credential value you copy once. Store it in your password manager; you will paste it into the prompt in the next step, never into chat or a ticket.

3. Run auth init with a named context

Use the context flag so this login has a name. Team names work well, or team plus environment.

doctl auth init --context [team-name]

Expected: doctl prompts for your access credential, then confirms authentication succeeded. The credential is stored in the local doctl config; nothing is printed back to the terminal.

4. Verify the context can read the account

Confirm the new context actually works before you rely on it.

doctl account get --context [team-name]

Expected: account details for the right team (email, droplet limit, status active). If the account shown is not your team, you pasted the wrong credential; re-run step 3.

5. List and switch contexts

Check what is configured and switch explicitly in every command or script.

doctl auth list

Expected: a table of your contexts with one marked current. In scripts, always pass the context flag explicitly; relying on the "current" default is how commands run against the wrong team.

Variant: onboarding a new teammate in five minutes

Send them steps 2 through 4 plus the agreed context naming convention. The whole flow is: create credential, run auth init with the team context name, verify with account get. No shared credentials, no screenshots of credentials.

Variant: one machine, two teams

Run step 3 twice with different context names. Keep the names obvious, like [company]-prod and [company]-staging. A wrapper alias per context saves typing and prevents mistakes.

Why this happens

doctl keeps one default auth context, so the second login silently replaces the first unless you name them. Named contexts give each team login its own slot, which is why the fix is always "name the context" rather than "re-authenticate harder."

Edge cases and pitfalls

• Pasting a credential into a shared terminal or screen share: create the credential, use it, revoke if exposed.
• Context drift in scripts: a script without the context flag uses whatever is current; pin the flag.
• Credential scopes too narrow: read-only credentials fail on create and delete commands with permission errors, not auth errors.
• Stale config after a team leaves: remove dead contexts so auth list stays honest.
• Multiple people sharing one machine account: each person should still use their own credential and context, or use separate OS users.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstYbUXqUt9qBq0LUzuRx9kA