Authenticate the Dosya CLI safely
Sign in interactively, through stdin, or with DOSYA_API_KEY; verify the account, understand credential precedence, and revoke stored access safely.
Last reviewed
The Dosya CLI authenticates with a dos_ API key. Use the hidden interactive prompt on a personal terminal, pipe the key through standard input for a setup script, or provide DOSYA_API_KEY to an automation environment. Avoid putting a reusable secret directly after --key, where shell history and the process list can expose it.
Create a key for this CLI installation
Open Profile → API keys, select New API key, and label it for this machine or automation job. Choose the smallest permission that supports the intended commands:
- Read only can list and download but cannot upload, move, or delete.
- Upload only can add files but cannot list or download stored files.
- Full access supports commands that read and modify content, subject to workspace role permissions.
Under Protocols, include REST API because the CLI calls REST endpoints. Add a workspace pin, IP ranges, active hours, usage limits, or expiry when those restrictions fit the job. Save the one-time full token; the key table shows only a prefix afterward.

Steps
Run the interactive command and paste the key when the hidden prompt appears:
dosya auth login
dosya whoami
Successful login prints Authenticated as NAME (EMAIL). dosya whoami then prints the account name, email, user ID, and workspace count; dosya whoami --json emits the account object for a script.
The CLI stores the token and API base in ~/.dosya/config.json, or $XDG_CONFIG_HOME/dosya/config.json when XDG_CONFIG_HOME is set. The directory is created with mode 0700 and the file with 0600 on Unix-like systems. The key is plain text inside that protected file. If restored permissions allow group or other users to read it, the CLI warns with a corrective chmod 600 command.
Authenticate a setup script without argv exposure
Pipe the key through stdin:
printf '%s\n' "$MY_KEY" | dosya auth login --key -
dosya whoami --json
An empty pipe fails with No API key on stdin. A non-interactive run without --key - or DOSYA_API_KEY fails with Cannot prompt for API key in non-interactive mode. A value that does not begin with dos_ is rejected before the network request.
For CI or a short-lived container, inject the key as an environment secret and skip writing it to disk:
export DOSYA_API_KEY="$MY_KEY"
dosya whoami --json
Credential precedence is --key, then DOSYA_API_KEY, then the stored config. API endpoint precedence is DOSYA_API_BASE, then the config file, then https://api.dosya.dev. Know which source wins before diagnosing a surprising account or environment.

Fix common authentication failures
| CLI output | What to do |
|---|---|
Authentication failed: invalid API key. | Copy the complete one-time token or create a replacement if the original value is no longer available. |
Not authenticated. Run: dosya auth login | Supply DOSYA_API_KEY or complete a stored login. |
Authentication failed. Run 'dosya auth login' to re-authenticate. | The server returned 401; check expiry or revocation and replace the credential. |
Permission denied. You don't have access to this resource (403). | The key remains live, but its scope, protocol, source conditions, workspace pin, or current role refused the operation. |
| A key works locally but fails in CI | Compare the injected key, DOSYA_API_BASE, source IP allowlist, active-hours timezone, and selected workspace membership. |
Exit code 3 means authentication failure, 5 means a live credential was forbidden, 4 means a network failure, and 2 means invalid CLI usage. Automation should not respond to exit 5 by repeatedly logging in again.
Log out or revoke the key
dosya auth logout removes the local config file only. The API key continues working elsewhere until it expires or is revoked:
dosya auth logout
To destroy the stored key on the server and then clear the local file, run:
dosya auth logout --revoke
Server-side revocation is irreversible. It deletes the key and requests cache invalidation. Cached authentication can remain accepted until caches clear or expire; stop old clients and verify refusal before treating access as closed. If revocation fails, the CLI keeps the local credential so the command can be retried. A 401 means the stored key is already invalid, so the CLI safely clears it. An environment-only DOSYA_API_KEY is not managed by logout; revoke that credential from Profile → API keys.
Expected result
dosya whoami identifies the intended account without printing the key. The credential source and endpoint are known, the stored file is owner-readable only when used, and the key can be independently revoked when this CLI installation is retired.
Related guides
Was this helpful?
Loading helpfulness results…
Voting saves a necessary ballot cookie for up to 180 days so you can change your answer.
Questions and replies
Ask about the steps in this guide. Questions are reviewed before publication.
Keep account details, credentials and private files out of public questions. Use private support for those.
Loading questions…
Sign in to your Dosya account to ask a question.