dclient/docs/authentication.md

(authentication)=

Authentication

dclient can handle API tokens for Datasette instances that require authentication.

You can pass an API token to any command using --token like this:

dclient query fixtures "select * from facetable" --token dstok_mytoken -i latest

A more convenient way to handle this is to store tokens for your aliases.

Logging in with OAuth

The easiest way to authenticate is using the dclient login command, which uses the OAuth device flow to obtain and store a token.

This requires the Datasette instance to be running the datasette-oauth plugin with device flow enabled.

dclient login https://my-datasette.example.com/
dclient login myalias
dclient login

This will display a URL and a code. Open the URL in your browser, enter the code to approve access, and the resulting API token will be saved automatically. If you run dclient login without an argument, you will be prompted for the instance URL or alias.

You can also pass a --scope option to request specific permissions:

dclient login myalias --scope '[["view-instance"]]'

dclient login --help

Usage: dclient login [OPTIONS] [ALIAS_OR_URL]

  Authenticate with a Datasette instance using OAuth

  Uses the OAuth device flow: opens a URL in your browser where you approve
  access, then saves the resulting API token.

  Example usage:

      dclient login https://simon.datasette.cloud/
      dclient login myalias
      dclient login

Options:
  --scope TEXT  JSON scope array
  --help        Show this message and exit.

Using stored tokens

To store a token for an alias:

dclient auth add latest

Then paste in the token and hit enter when prompted to do so.

Tokens can also be stored for direct URLs:

dclient auth add https://latest.datasette.io

To list which aliases/URLs you have set tokens for, run the auth list command:

dclient auth list

To delete the token for a specific alias or URL, run auth remove:

dclient auth remove latest

Token resolution order

When making a request, dclient resolves the token in this order:

1. --token CLI flag (highest priority)
2. Token stored by alias name in auth.json
3. Token stored by URL prefix in auth.json
4. DATASETTE_TOKEN environment variable (lowest priority)

Testing a token

The dclient auth status command can be used to verify authentication by calling /-/actor.json:

dclient auth status
dclient auth status -i prod

The dclient actor command also shows the actor:

dclient actor
dclient actor -i prod

The output looks like this:

{
    "actor": {
        "id": "root",
        "token": "dstok"
    }
}

dclient auth --help

Usage: dclient auth [OPTIONS] COMMAND [ARGS]...

  Manage authentication for different instances

Options:
  --help  Show this message and exit.

Commands:
  add     Add an authentication token for an alias or URL
  list    List stored API tokens
  remove  Remove the API token for an alias or URL
  status  Verify authentication by calling /-/actor.json

dclient auth add --help

Usage: dclient auth add [OPTIONS] ALIAS_OR_URL

  Add an authentication token for an alias or URL

  Example usage:

      dclient auth add prod
      dclient auth add https://datasette.io

  Paste in the token when prompted.

Options:
  --token TEXT
  --help        Show this message and exit.

dclient auth list --help

Usage: dclient auth list [OPTIONS]

  List stored API tokens

  Example usage:

      dclient auth list

Options:
  --help  Show this message and exit.

dclient auth remove --help

Usage: dclient auth remove [OPTIONS] ALIAS_OR_URL

  Remove the API token for an alias or URL

  Example usage:

      dclient auth remove prod

Options:
  --help  Show this message and exit.

dclient auth status --help

Usage: dclient auth status [OPTIONS]

  Verify authentication by calling /-/actor.json

  Example usage:

      dclient auth status
      dclient auth status -i prod

Options:
  -i, --instance TEXT  Datasette instance URL or alias
  --token TEXT         API token
  --help               Show this message and exit.

dclient actor --help

Usage: dclient actor [OPTIONS]

  Show the actor represented by an API token

  Example usage:

      dclient actor
      dclient actor -i prod

Options:
  -i, --instance TEXT  Datasette instance URL or alias
  --token TEXT         API token
  --help               Show this message and exit.