doctl-auth

Open a prompt to enter an API token and label its context

$ doctl auth init --context [token_label]

$ doctl auth [[ls|list]]

$ doctl auth switch --context [token_label]

$ doctl auth remove --context [token_label]

$ doctl auth [[-h|--help]]

doctl auth command [options] [arguments]

Common doctl auth commands:
  doctl auth init [--access-token token] [--context name]
  doctl auth current
  doctl auth list
  doctl auth switch context-name
  doctl auth remove context-name

init
    Initializes a new or default authentication context, often by prompting for a DigitalOcean API access token.

current
    Displays the name of the currently active authentication context.

list
    Lists all configured authentication contexts.

switch context-name
    Changes the active authentication context to the specified context-name.

remove context-name
    Removes the specified authentication context from doctl's configuration.

--access-token token
    (Optional, for init) Specifies the DigitalOcean API access token directly, bypassing the interactive prompt. Caution: Providing tokens on the command line may expose them in shell history.

--context name
    (Optional, for init, switch, remove) Specifies the name for a new context during initialization, or identifies the context to switch to or remove.

The doctl auth command group is responsible for configuring and managing authentication to the DigitalOcean API for the doctl command-line client.

It allows users to log in with their DigitalOcean API access tokens, set up and switch between different authentication contexts (e.g., for multiple DigitalOcean accounts or projects), and list or remove existing contexts. The primary use case is doctl auth init, which guides the user through providing an API token and saves it securely for future commands. This ensures that subsequent doctl commands can interact with DigitalOcean resources on behalf of the authenticated user without needing to re-enter credentials.

Security of API Tokens: DigitalOcean API tokens grant programmatic access to your account. Treat them like passwords. Avoid hardcoding them or exposing them in public repositories. Using the --access-token flag on the command line can leave the token visible in your shell's command history.

Context Management: Carefully manage multiple contexts to ensure you are interacting with the correct DigitalOcean account or project, especially when running automated scripts.

To use doctl auth init, you need a DigitalOcean API token. These can be generated from the DigitalOcean Cloud Control Panel under API > Tokens/Keys. It is recommended to generate a new token for doctl with appropriate read/write permissions depending on your intended usage.

A doctl 'context' is a named configuration profile that stores an API token and optionally other settings. It allows you to quickly switch between different DigitalOcean accounts or sets of permissions without re-authenticating each time. For example, you might have contexts for 'personal-account', 'work-project-A', and 'staging-environment'.

doctl is the official command-line interface for the DigitalOcean API, developed and maintained by DigitalOcean itself. The doctl auth subcommand is a foundational component, introduced early in doctl's development lifecycle, as robust authentication management is critical for interacting with cloud resources. Its design reflects the need for both simplicity (easy initial setup) and flexibility (managing multiple contexts for different projects or teams).

doctl(1), doctl-account(1), doctl-compute(1)