# Authentication

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

The CLI calls the Kenso API with a Kenso API key (`kenso_live_` plus 49 characters, or an older key: `ken_` plus 43 characters). It sends the key as `Authorization: Bearer <key>` and never prints it, logs it or puts it in an error.

`kenso login`, `kenso logout` and `kenso whoami` are the same commands as `kenso auth login`, `kenso auth logout` and `kenso auth status`.

## Log in with an API key

1. In app.ken.so, go to Settings > Integrations > API keys and create a key.
2. Pipe it to `kenso auth login --with-key`. The key is read from stdin, never from a flag, so it stays out of your shell history and process list.

```bash
echo $KEY | kenso auth login --with-key
kenso auth login --with-key --profile client-a --workspace 1234 < key.txt
```

The CLI checks the key with `GET /v1/me`, then saves it to `~/.kenso/config.json` (file mode 0600, folder mode 0700). It prints:

```json
{"profile":"default","email":"you@acme.io","workspaceId":"1234","workspaceCount":1}
```

A developer sandbox does not count here unless every workspace is one: a key whose user has one workspace and a sandbox saves that workspace. When the key reaches several workspaces and you did not pass `--workspace`, no workspace is saved and the output carries `"next":"kenso workspace list --search <name>"`. A key in the wrong format exits 2 (`invalid_key_format`). A key Kenso rejects exits 3.

## Browser login

```bash
kenso auth login
kenso auth login --no-browser --device-name "build box"
```

Browser login is available to every workspace. The CLI prints a link and a code on stderr. You open the link, sign in to app.ken.so, check that the code matches the one in your terminal, pick the workspace to start in and approve. The CLI then saves a new API key to the profile and prints:

```json
{"profile":"default","email":"you@acme.io","workspaceId":"1234","keyExpiresAt":"2027-02-02T06:26:59Z"}
```

The key is the same kind you create in the app. It is named `Kenso CLI - <device name>` (`--device-name`, else `kenso-cli on <hostname>`), lasts 90 days, and shows in your API key list at Settings > Integrations > API keys, where you can revoke it. The CLI opens the browser itself only when no coding agent is detected and the machine has a display. An agent prints the link and asks you to open it. The login expires after 10 minutes (`login_expired`, exit 3), and a denied login exits 3 with `access_denied`. If the API answers that browser login is off (`browser_login_unavailable`, exit 3, `"next":"kenso auth login --with-key"`), log in with an API key as above.

## CI, scripts and agents: use the environment

You do not need to log in on a machine that has the key in its environment:

```bash
export KENSO_API_KEY=kenso_live_...
export KENSO_WORKSPACE_ID=1234
kenso auth status
```

`KENSO_API_KEY` wins over any saved profile. Store it as a secret in your CI or agent platform, never in a file in the repo.

## Workspaces

A key reaches every workspace its user belongs to. Each command runs in one workspace, picked in this order:

1. `--workspace <id>` on the command
2. `KENSO_WORKSPACE_ID`
3. the workspace saved in the profile (`kenso workspace use`)

```bash
kenso workspace list --search acme
kenso workspace use 1234
kenso campaigns list --workspace 5678
```

`workspace list` prints one page and says on stderr when there are more: add `--all` for every page. A command that needs a workspace when none is picked fails with `workspace_required` (exit 2) and `"next":"kenso workspace list --search <name>"`.

## Workspace-owned keys

A workspace admin can create a key the workspace owns: it keeps working when the admin leaves and acts with exactly the permissions of its template (`admin`, `editor` or `viewer`). Workspace keys are on for every workspace. The command is in beta: `kenso --help` and `kenso workspace --help` list it, marked beta, once the CLI has read the workspace's features from `GET /v1/me`. When it cannot read them (no key, or the lookup fails or takes more than 1.5 seconds), help hides the command and names it on its "Beta, hidden" line instead; `--all-commands` shows it. It runs when typed either way.

```bash
kenso workspace keys create --name "Zapier sync" --template editor --expires-in-days 90
```

No API key may create a workspace key, the one the CLI logs in with included. The command prints the API's refusal (`forbidden`) with `"next":"A workspace admin can create it in the app: Settings > API keys > Workspace keys"` and exits 3, without retrying. A member who is not a workspace admin gets a 403 too (`permission_denied`), with the same next step. An admin creates the key there; the secret is shown once.

## Profiles

A profile holds a key, a workspace, an optional API URL and the email. Use one per client or per key:

```bash
kenso auth login --with-key --profile client-a < client-a-key.txt
kenso campaigns list --profile client-a
KENSO_PROFILE=client-a kenso auth status
```

The profile is `--profile`, else `KENSO_PROFILE`, else the active one (the last one you logged in to).

## Check the setup

```bash
kenso auth status
kenso doctor
```

`auth status` prints who the key belongs to and when it expires, and warns on stderr when that is within 14 days:

```json
{"email":"you@acme.io","workspaceCount":3,"activeWorkspace":{"id":"1234","name":"Acme"},"keyExpiresAt":"2027-01-31T00:00:00Z","keySource":"profile","profile":"default"}
```

`doctor` prints the version, Node, the config folder, the profile, the key source, the API URL, the workspace and the detected agent, then four checks: `node_version`, `config_permissions`, `api_reachable` and `key_valid`. It exits 0 when every check passes, 3 when the key is missing or rejected, else 1.

## Log out

```bash
kenso auth logout
kenso auth logout --profile client-a
kenso auth logout --keep-key
```

This removes the profile and its key from this machine. When browser login made the key, logout revokes it first, so it stops working everywhere; `--keep-key` leaves it valid. If the revoke fails (no network, or the key was already revoked), logout warns and still removes the profile. A key you saved with `--with-key` was made by you in the app, so logout leaves it valid: revoke it at Settings > Integrations > API keys. The output adds `revoked: true` or `false`.

## Where things live

| What | Default | Override |
|---|---|---|
| Config file with profiles and keys | `~/.kenso/config.json` | `KENSO_CONFIG_DIR` |
| Run folders | `~/.kenso/runs/` | `KENSO_RUNS_DIR` |
| Cached workspace features (1 hour) | `~/.kenso/cache/` | follows `KENSO_CONFIG_DIR` |
| Last update check (once every 7 days) | `~/.kenso/update-check.json` | follows `KENSO_CONFIG_DIR`; `KENSO_NO_UPDATE_NOTIFIER=1` turns the check off |
| API | `https://api.ken.so` | `KENSO_API_URL` |
| MCP (for `kenso mcp`) | `https://mcp.ken.so/mcp` | `KENSO_MCP_URL` |

`--verbose` prints each request line to stderr with the key redacted.

## More for developers

- [API docs](/docs)
- [MCP server](/mcp)
- [Interactive API reference](https://developer.ken.so/reference/)
- [Changelog](/docs/changelog)
