Skip to content
Subaya

Authentication & API keys

Subaya supports two authentication modes against the same API.

API keys — SUBAYA_API_KEY (agents & CI)

Section titled “API keys — SUBAYA_API_KEY (agents & CI)”

The simplest path, and the one to use for AI agents and CI pipelines. Set the environment variable and every suya command (and the platform API) picks it up:

Terminal window
export SUBAYA_API_KEY="sk_live_..."
suya auth whoami      # confirm the identity the key resolves to

No browser, no interactive step — ideal for headless environments. Issue and manage keys from the console, under Settings → API keys.

Keys are per environment

Section titled “Keys are per environment”

The prefix tells you which environment a key belongs to, and a key only works against that one:

  • sk_live_… — the production API (https://subaya-dev.com).
  • sk_test_… — reserved for non-production environments.

Present a key to the wrong host and suya auth whoami rejects it with wrong_environment (not a generic “invalid key”), and tells you where to mint the right one. See CLI: auth for the full list of reasons.

OAuth browser login (humans)

Section titled “OAuth browser login (humans)”

For interactive use on a workstation:

Terminal window
suya auth login                 # opens a browser (loopback redirect)
suya auth login --no-browser    # print a code to approve from any device

suya auth login opens a browser and redirects back to 127.0.0.1, so it needs the browser to be on the same machine. When it isn’t — SSH, a container, a remote dev box — use --no-browser: the CLI prints a short code, you approve it in a browser on any device, and the CLI picks up the token. It also switches to that flow on its own if the browser can’t be opened or the redirect never arrives. See the device-flow walkthrough.

The CLI stores the resulting token locally (under ~/.config/suya/). Check or clear it:

Terminal window
suya auth status    # local status, without calling the server
suya auth logout    # log out and revoke the local token

Precedence

Section titled “Precedence”

When more than one credential is present, suya resolves in this order:

  1. The --token global flag
  2. SUBAYA_API_KEY
  3. The locally stored OAuth token (~/.config/suya/auth.json)

Pointing at a different host

Section titled “Pointing at a different host”

All commands accept --host (default https://subaya-dev.com) if you need to target a non-default API endpoint.

Next steps

Section titled “Next steps”