Authentication

Every command that calls the API requires a personal access token. Create one on the Developer Center Access tokens page; token types and scopes are described in Generating an API token. The CLI reads the token from --token-stdin, DEEL_TOKEN, or the OS keychain, validates it on request, and never writes it to disk outside the OS keychain.

When an AI agent uses the CLI, the agent never handles the token: it runs deel commands and the CLI resolves the token from the sources below.

Token sources

The CLI checks the following sources in order and uses the first one that yields a token.

--token-stdin and DEEL_TOKEN are ephemeral: the value is used for the current process and never written anywhere. The keychain is the only persisted store. For interactive use, prefer the keychain over exporting DEEL_TOKEN in a shell profile.

Manage the stored token

deel auth login                  # prompt for the token with hidden input, validate, store
echo "$DEEL_PAT" | deel auth login   # non-interactive: read the token from stdin
deel auth status                 # validate the current token and report its source
deel auth logout                 # remove the stored token for the selected environment

The CLI stores tokens per environment: storing a token for the demo environment with deel auth login --env demo does not affect the production entry. All three commands accept --env.

deel auth login validates the token against the API before storing it. If the validation request fails, nothing is stored and the command exits with an auth.invalid error.

Output of deel auth status

deel auth status --env demo

{
  "data": {
    "valid": true,
    "source": "keychain",
    "token": "****a1b2",
    "identity": {
      "id": 482915,
      "email": "jane.doe@example.com",
      "full_name": "Jane Doe",
      "profile_type": "client",
      "organization_id": 91043,
      "organization_name": "Acme Corporation"
    }
  }
}

Fields of the data object:

Keychain backends

Each platform uses its own keychain backend:

deel auth login exits with auth.keychain and a suggested alternative when no keychain is available.

Tokens for agents, CI, and scripts

On a developer machine, store the token in the keychain with deel auth login; a coding agent running in your shell can then use the CLI without ever seeing the token value. In containers, hosted agents, and CI, inject the token as a secret and pass it through the environment or stdin. Do not write it to a file in the workspace.

# Environment variable (simplest)
export DEEL_TOKEN="$DEEL_PAT_SECRET"
deel jobs list --fields job_id,status
# stdin (keeps the token out of the process environment)
printf '%s' "$DEEL_PAT_SECRET" | deel jobs list --token-stdin

Scopes attached to the token determine which commands succeed. A command outside the token’s scopes fails with a 403 error in the error envelope.

Token safety

• The CLI refuses to send a token over a non-HTTPS URL and exits with network.insecure.
• Tokens are redacted from local logs: the Authorization header is recorded as Bearer ***, and tokens never appear in log files or in --debug output.
• deel auth status and deel auth login print the token masked to its last four characters.
• Tokens stored in the keychain are readable only by your OS user.

For the full list of safeguards, see Security and permissions.

Next steps