> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/cli/authentication/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Authentication

> How the Deel CLI resolves, validates, and stores your API token

Every command that calls the API requires a personal access token. Create one on the Developer Center [Access tokens page](https://app.deel.com/settings/developer/tokens); token types and scopes are described in [Generating an API token](/api/authentication#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.

| Precedence | Source          | How to provide it                                  | Persisted            |
| ---------- | --------------- | -------------------------------------------------- | -------------------- |
| 1          | `--token-stdin` | `echo "$DEEL_PAT" \| deel <command> --token-stdin` | No                   |
| 2          | `DEEL_TOKEN`    | `export DEEL_TOKEN="$DEEL_PAT"`                    | No                   |
| 3          | OS keychain     | Stored by `deel auth login`, read automatically    | Yes, per environment |

`--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

```bash
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`

```bash
deel auth status --env demo
```

```json
{
  "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:

| Field      | Description                                               |
| ---------- | --------------------------------------------------------- |
| `valid`    | `true` if the token was accepted                          |
| `source`   | Where the token originated: `stdin`, `env`, or `keychain` |
| `token`    | The token masked to its last four characters              |
| `identity` | Identity fields of the token owner                        |

## Keychain backends

Each platform uses its own keychain backend:

| Platform | Backend                   | Requirement                                                                                                                           |
| -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| macOS    | Keychain (`security`)     | Built in                                                                                                                              |
| Linux    | libsecret (`secret-tool`) | Install `libsecret-tools` (Debian, Ubuntu) or `libsecret` (Fedora) and run a Secret Service provider such as GNOME Keyring or KWallet |
| Windows  | None                      | Use `DEEL_TOKEN` or `--token-stdin`                                                                                                   |

`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.

```bash
# 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](/cli/usage/errors).

## 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](/cli/usage/security).

## Next steps

#### [Environments and configuration](/cli/usage/environments)

Select production or demo and configure the CLI through environment variables

#### [Set up a coding agent](/cli/agents/setup)

Give an agent a scoped token without exposing it

> Build apps and integrations that extend and enhance the Deel services.