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.

Dosya CLI authentication choices for a hidden prompt, standard input, or an environment secret followed by an identity check.
Choose the credential source for the environment, verify it with `dosya whoami`, and keep revocation available through the named API-key record. Open full-size screenshot.

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.

Dosya Profile API-key list with separate named credentials that can be recognized and revoked per CLI installation.
Name each CLI credential for its machine or job so the correct key can be revoked without changing unrelated integrations. Open full-size screenshot.

Fix common authentication failures

CLI outputWhat 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 loginSupply 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 CICompare 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.

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.

    Check the outcome before you retry

    Use these shared checks when a task needs a second look.