---
title: Authentication
description: Log in to your AKOS workspace, manage provider credentials, store secrets in the vault, and provision integration connections.
---

The CLI authenticates to your AKOS workspace via a device-code OAuth flow. Once logged in, provider credentials and secrets are managed separately through the `creds`, `vault`, `secrets`, and `connections` commands.

## Logging in

```bash
akos auth login
```

This starts a device-code flow:

1. The CLI prints a verification URL and a short user code.
2. Open the URL in a browser and enter the code.
3. After approval, the CLI saves your session token locally and prints `Logged in as <userId>`.

### Login options

| Flag | Description |
|---|---|
| `--scope <scope>` | OAuth scope (default: `cli`) |
| `--client-id <id>` | Override the OAuth client ID |

### CI environments

If the environment variable `AKOS_TOKEN` is already set, `auth login` exits immediately with a success message. Use this for non-interactive pipelines.

## Checking your session

```bash
akos auth whoami
```

Prints `Logged in as <userId> on tenant <tenantId>` and confirms the workspace is reachable. Add `--json` for machine-readable output.

## Switching tenants

When your account belongs to multiple tenants (OEM multi-tenancy), use the `tenant` commands to list and switch:

```bash
akos tenant list
```

Lists all tenants your account can access. If you do not have the `oem:tenant:admin` role, the command falls back to reporting the current tenant.

```bash
akos tenant use <tenant-id>
```

In local/self-host mode, this persists the tenant ID to your local session for subsequent sidecar calls. In hosted/cloud mode, tenant switching is server-side; re-login or use the hosted tenant switch flow so token claims and tenant isolation stay aligned.

## Logging out

```bash
akos auth logout
```

Clears the locally stored session token. Safe to call when no session exists (idempotent).

## Managing provider credentials

The `creds` command lists, verifies, and stores the API keys required by AI providers and integrations. Values are never printed.

### List known providers

```bash
akos creds list
```

Shows each provider, its kind, and the vault keys it requires.

Filter by kind or provider:

```bash
akos creds list --kind llm
akos creds list --provider anthropic
```

Output as JSON:

```bash
akos creds list --json
```

### Check credential presence

```bash
akos creds check
```

Scans the environment (and optionally a secrets file) for each required key. Exits with code 0 when all keys are present, code 7 when any are missing.

```bash
# Check against a local dotenv-style file (key names only — values never shown)
akos creds check --secrets-file .env.local

# Skip cloud providers (air-gapped workspace)
akos creds check --air-gap

# Restrict to a specific provider
akos creds check --provider openai
```

### Set a credential

```bash
akos creds set
```

Interactive guided flow for storing a credential. Follows the same vault backend as `vault put`.

### Onboarding guide

Print the full credential onboarding playbook:

```bash
akos creds guide
```

## Vault: workspace secrets

The `vault` command reads and writes secrets in the workspace vault. Secret **values are never printed** — only key names and their source are shown.

### Store a secret

```bash
akos vault put OPENAI_API_KEY sk-...
```

Scope the secret to a tenant instead of the workspace:

```bash
akos vault put STRIPE_SECRET_KEY sk_live_... --scope tenant
```

Scopes: `workspace` (default), `tenant`.

### List stored secrets

```bash
akos vault list
```

Shows key names and their source (e.g. `os-keychain`). Add `--json` for machine-readable output.

## Secrets: headless provisioning

The `secrets` command is a headless alternative to `vault`, operating through the running workspace sidecar. Use it when scripting in environments where the sidecar is already running.

```bash
# Store a secret
akos secrets set GITHUB_TOKEN ghp_...

# List stored keys (values hidden)
akos secrets list

# Filter output as JSON
akos secrets list --json
```

Scope options (`--scope workspace|tenant`) work the same as `vault put`.

## Integration connections

Integration connections link your workspace to external services (Slack, GitHub, Stripe, and others). Authentication always references a vault key — never a plaintext token.

### Provision a connection

First, store the credential in the vault:

```bash
akos vault put SLACK_BOT_TOKEN xoxb-...
```

Then create the connection, referencing the vault key:

```bash
akos connections set \
  --id slack-main \
  --kind slack \
  --label "Main Slack workspace" \
  --secret-id SLACK_BOT_TOKEN
```

For integrations that require no auth:

```bash
akos connections set \
  --id public-webhook \
  --kind webhook \
  --label "Inbound webhook" \
  --no-auth
```

Supported kinds: `slack`, `github`, `linear`, `discord`, `email`, `cron`, `file`, `webhook`, `cdc`, `twilio`, `sentry`, `pagerduty`, `stripe`, `s3`, `mcp`, `llm`.

### List connections

```bash
akos connections list

# Filter by kind
akos connections list --kind slack

# JSON output
akos connections list --json
```

### Inspect a connection

```bash
akos connections get slack-main
```

### Remove a connection

```bash
akos connections rm slack-main
```

Removing a connection does not delete the underlying vault secret.

## Related topics

- **[Connections (CLI)](/docs/cli/connections)** — `connections guide`, provision, and `connectors test`.
- **[Connections in the app](/docs/using-the-app/connections)** — OAuth cards, external secrets, SQL, cloud sync.
- **[Integration setup](/docs/using-the-app/integration-setup)** — registry-backed setup guides for providers.
- **[CLI index](/docs/cli)** — `doctor`, shell completion, and CI token patterns.