Authentication

The CLI runs on one credential: your session token from the device-flow login. Every command accepts it — management and decision commands alike. There is no API-key access to the management API.

Workspace API keys are the application-side credential: the SDK sends one as its apiKey constructor option, and the decision endpoints accept it in place of a session. When both credentials arrive, the key wins — and a bad key is rejected without falling back to the session.

Logging in

arkveil auth login

This requests a device code and opens your browser to complete an OAuth 2.0 Device Authorization Grant (RFC 8628) against the backend's device authorization endpoint. The browser step signs you into an existing Arkveil account — register in Arkveil Studio and confirm your email before your first login. The CLI polls for the token, handling authorization_pending, slow_down, expired_token, and access_denied responses.

arkveil auth login --no-browser   # print the URL/code instead of opening a browser

Other auth commands:

arkveil auth logout               # remove stored credentials
arkveil auth whoami [--no-verify] # show who you're logged in as

Credential storage

Tokens are sent as an Authorization: Bearer <token> header on every request. They're stored in your OS keychain via keytar when available, or in ~/.config/arkveil/credentials.json (mode 0600) otherwise. arkveil auth whoami reports which backend is active.

Bypassing stored credentials

arkveil --api-key "$TOKEN" ...
# or
ARKVEIL_TOKEN=$TOKEN arkveil ...

Workspace API keys

Workspace API keys authenticate your application's SDK. The decision endpoints accept them in place of a session, but the CLI itself does not need one — your login covers it:

arkveil keys list
arkveil keys create   # secret is shown once — save it immediately

Selecting a workspace

Without an explicit workspace id, the CLI falls back to your oldest workspace. If you belong to more than one workspace, set one explicitly:

arkveil --workspace <id> ...
# or
ARKVEIL_WORKSPACE_ID=<id> arkveil ...
# or in the config file
{ "workspaceId": "<id>" }

This is sent as the X-Workspace-Id header on every request.