CLI & API auth

Destesi authenticates you in two modes, depending on where you are calling from:

• In a browser — a single sign-on session cookie, established when you log in at account.destesi.io.
• From the CLI, the API, or a service — a bearer token (a personal access token) sent in the Authorization header.

Both end up authenticating the same account, scoped to the same workspace. You pick the mode that fits the context.

Browser: session cookies

When you log in at account.destesi.io and open a product, that product holds a host-only session cookie. This is the single sign-on session described in Accounts & SSO — it is set up for you automatically and renewed silently while you work. You do not manage it by hand; it is the default for everything you do in the web apps.

CLI & API: bearer tokens

Outside the browser, you authenticate with a personal access token — a single token tied to your account that every product accepts. You mint it once from your account and send it on every request:

Authorization: Bearer idn_pat_<token>
X-Destesi-Workspace: <workspace-slug>

The token is account-scoped, but a request always acts inside one workspace, so you name the workspace with the X-Destesi-Workspace header. The same token can address any workspace you belong to — just change the header. The plaintext token is shown to you once when you mint it — store it somewhere safe, because it cannot be retrieved again.

Caution

A malformed or unrecognized Authorization: Bearer header is rejected outright — the request is not silently retried as if it were unauthenticated. Send a valid idn_pat_ token.

Using the dst CLI

The dst CLI authenticates once and stores its credential locally. There are two ways to log in:

Browser login

dst login

This opens your browser to approve the login, then saves the resulting token to ~/.dst/config.yaml. If the browser does not open, the command prints a URL and a code to enter manually.

Token login

dst login --token <your-token>

Paste a personal access token you minted from your account. The credential is saved to ~/.dst/config.yaml with no browser round-trip — handy for headless and CI environments.

Once logged in, every dst subcommand uses the saved credential automatically. To sign out and clear the stored credential:

dst logout

From your own code

For scripts and services, set the token as an environment variable and send it as a bearer token. For the dst CLI you can supply the credential via DESTESI_API_KEY instead of logging in:

export DESTESI_API_KEY="<your-token>"

Calling a product’s HTTP API directly is the same idea — attach the token and name the workspace:

curl -H "Authorization: Bearer idn_pat_<token>" \
  -H "X-Destesi-Workspace: <workspace-slug>" \
  https://api.<product>.destesi.io/v1/...

Note

Personal access tokens are minted and revoked from your account at account.destesi.io. A token is for using the products — manage the tokens themselves from your account.

Which mode do I use?

You are…	Use
Clicking around the web apps	Browser session (automatic)
Running dst on your machine	dst login (browser)
Running in CI or a headless box	dst login --token or DESTESI_API_KEY
Calling a product API from code	Authorization: Bearer idn_pat_<token> + X-Destesi-Workspace

Related concepts

Accounts & SSOHow the browser session works.

WorkspacesThe scope a key acts within.

EntitlementsWhat a key is allowed to reach.