keys
List, create, rotate and revoke API keys, remove a project from a key, and hand the stored key to an SDK
keys manages the account's API keys and hands the key stored on this computer to an SDK. A key belongs to the account and holds a list of projects; every app names its project with SOLWYN_PROJECT. See API keys.
list, create, rotate, revoke and remove-project need a Solwyn login: an API key can't manage keys. create, rotate, revoke and remove-project each need a one-time browser approval and the owner or admin role. env needs no login: it reads the key stored on this computer for the selected project.
A key is shown once, when it is created or rotated, unless it is stored on this computer instead. Listing never shows key material.
The CLI creates a key for one project. Only the dashboard can add another project to a key (Settings > API keys). solwyn keys add-project exits 2 and prints that dashboard link.
keys list
List the account's live keys and their projects, and mark the projects whose key is stored on this computer.
solwyn keys list
solwyn --json keys listThe JSON form (solwyn.keys-list.v1) carries each key's id, name, key_prefix, scope, created_via, created_by, created_at, expires_at, last_used_at, rotation_grace_until, status (active, grace or expired) and projects (each with id, name, budget_mode and dedicated_keys_only), plus stored_here, the projects this computer holds the key for. used and limit give the account's key count against its plan limit (-1 is unlimited).
| Contract | |
|---|---|
| Auth | login |
| Exit codes | 0 success · 1 generic/API · 3 auth |
| JSON schema | solwyn.keys-list.v1 |
keys create
Create a key for one project. With --store-key it is stored on this computer for that project and nothing secret is printed; otherwise it is shown once, with export lines.
solwyn keys create [--project PROJECT] [--name NAME] [--scope full|read_only] [--store-key]| Option | Default | Purpose |
|---|---|---|
--project, -p | the selected project | Project name or proj_ id for the key. |
--name | the project's name | Key name. |
--scope | full | read_only keys can read but not check budget or record spend. |
--store-key | Store the new key on this computer for the project. |
$ solwyn keys create --project checkout-bot --store-key
Field Value
ID 6f1d0c9e-0000-4000-8000-0000000000f1
Name checkout-bot
Key prefix solwyn_sk_cdcdcdcdcdcdcdcd
Scope full
Status active
Projects checkout-bot
Created via cli
Expires 2027-11-04T10:12:00Z
Rotation grace until -
Stored yesWithout --store-key, a panel shows the full key once, followed by export SOLWYN_API_KEY='...' and export SOLWYN_PROJECT='proj_...' lines. In JSON output the key is the key field. Store it before you close the terminal; it can't be shown again.
Creating a key counts against the account's key limit. Past it, the API answers 402 with api_key_limit_reached; revoke a key or upgrade.
| Contract | |
|---|---|
| Auth | login (browser approval) |
| Exit codes | 0 success · 1 generic/API · 2 usage · 3 auth or storage · 6 approval |
| JSON schema | solwyn.keys-create.v1 |
keys rotate
Create a replacement that holds the same projects and reveal it once. The old key keeps working for a grace window so you can cut over without downtime.
solwyn keys rotate <key_id> [--grace-seconds INT] [--scope full|read_only] [--yes]| Option | Default | Purpose |
|---|---|---|
KEY_ID | required | Id of the key to rotate, from keys list. |
--grace-seconds | server default | Seconds the old key keeps working, 0 through 604800 (seven days). 0 stops it at once. |
--scope | keep current | Scope for the replacement. |
--yes | Acknowledge the displayed effects without prompting. |
When this computer stores the key, the stored copy is replaced and no secret is printed. Otherwise the replacement is shown once:
$ solwyn keys rotate 6f1d0c9e-0000-4000-8000-000000000001 --grace-seconds 345600 --yes
Field Value
ID 6f1d0c9e-0000-4000-8000-0000000000f1
Name checkout-bot
Key prefix solwyn_sk_cdcdcdcdcdcdcdcd
Scope full
Status active
Projects checkout-bot
Created via cli
Expires 2027-11-04T10:12:00Z
Rotation grace until -
Replaced key 6f1d0c9e-0000-4000-8000-000000000001
Old key works until 2026-11-08T10:12:00Z
Stored no
╭─────────────────────── One-time replacement API key ───────────────────────╮
│ solwyn_sk_cdcd… │
╰────────────────────────────────────────────────────────────────────────────╯The panel prints the full key (64 hexadecimal characters after solwyn_sk_), shown here truncated. In JSON output it is the key field. The replacement expires one year after the rotation. With --grace-seconds 0, apps still using the old key on a hard-limit project have their AI calls blocked at once.
| Contract | |
|---|---|
| Auth | owner/admin login (browser approval) |
| Exit codes | 0 success · 1 generic/API · 2 usage or confirmation · 3 auth · 5 not found · 6 approval |
| JSON schema | solwyn.keys-rotate.v1 |
keys revoke
Revoke a key now, without a replacement. Use it when a key is compromised and you have already rotated, or when you retire a key for good.
solwyn keys revoke <key_id> [--yes]KEY_ID is the key's id from keys list; never pass key material. The command also deletes this computer's stored copies of the key.
$ solwyn keys revoke 6f1d0c9e-0000-4000-8000-000000000001 --yes
Field Value
Key ID 6f1d0c9e-0000-4000-8000-000000000001
Revoked true
Removed from this computer proj_8a8a8a8a8a8a8a8a8a8a8a8aEvery app using the key stops reporting to Solwyn at once. On projects with a hard limit, or any hard cap on a model, provider, agent run or tag, their AI calls are blocked. On alert-only projects with no hard cap, their calls keep running, but Solwyn stops seeing that spend.
| Contract | |
|---|---|
| Auth | owner/admin login (browser approval) |
| Exit codes | 0 success · 1 generic/API · 2 usage or confirmation · 3 auth · 5 not found · 6 approval |
| JSON schema | solwyn.keys-revoke.v1 |
keys remove-project
Take a project away from a key. The key keeps its other projects.
solwyn keys remove-project <key_id> --project PROJECT [--yes]Apps using that key with SOLWYN_PROJECT set to that project stop making AI calls until they get a new key. A key keeps at least one project; revoke it instead of removing the last.
| Contract | |
|---|---|
| Auth | owner/admin login (browser approval) |
| Exit codes | 0 success · 1 generic/API · 2 usage or confirmation · 3 auth · 5 not found · 6 approval |
| JSON schema | solwyn.keys-remove-project.v1 |
rotate, revoke and remove-project show their effects on stderr, then require confirmation or --yes. Without a TTY and without --yes, they exit 2 before any request; declining, EOF and Ctrl-C send nothing. After an uncertain write, check keys list before you retry.
keys env
Print export lines for the key stored on this computer for the selected project, so an SDK can read SOLWYN_API_KEY and SOLWYN_PROJECT. The key stays in the CLI's credential store, and the hand-off creates no other file holding it.
(solwyn_env="$(solwyn --format table keys env)" && eval "$solwyn_env" && exec python app.py)Type or copy it as one line. This is the form solwyn keys env --help prints, with <command> in place of python app.py.
On success, keys env prints to stdout and nothing to stderr:
export SOLWYN_API_KEY='solwyn_sk_a1a1...a1a1'
export SOLWYN_PROJECT='checkout-bot'SOLWYN_PROJECT is the value from .solwyn.env when the repository has one, else the project as you gave it. A third line exports SOLWYN_API_URL when the CLI's API URL is not the default.
Use it as above:
- Run the app in a subshell. The parentheses keep the key and the exports inside the subshell, and
exechands them to the one command. Your shell never holds the key, so it can't reach a later command. - Nothing runs when the read fails. The
&&stops at the first failure. With no stored key for the project,keys envexits3withapi_key_not_storedand prints its error on stderr:No API key for <project> is stored on this computer. Run solwyn keys create --project <project> --store-key.Anevalof the command substitution outside a subshell hides that failure and runs your app without a key, and when the read succeeds it leaves the key exported in your shell. --format tablenames the format theevalexpects. Since 0.5.1,keys envprints export lines unless--jsonor--format jsonis on its own command line.SOLWYN_FORMAT=jsonand configformat = "json"never apply to it. NeverevalJSON output: theevalfails, and a shell such as zsh repeats the whole failing word, key included, in its error.
The project comes from --project, SOLWYN_PROJECT or the repository's .solwyn.env, in that order (see Choosing the project). If .solwyn.env names one project and --project or SOLWYN_PROJECT another, keys env exits 2 with project_mismatch before it prints anything. With a login, it turns a project name into an id through that login; without one, it matches the names of the keys stored here. It never reads SOLWYN_API_KEY and never writes .env or any other file. When the credential store itself can't be used, it exits 3 with credential_storage_failed and says what to fix. See Storage errors.
With --json or --format json on the command line, it returns solwyn.keys-env.v2: names, export (the lines), api_url, and project (selector and id).
| Contract | |
|---|---|
| Auth | local (the stored key; with a login, one project lookup) |
| Exit codes | 0 success · 2 usage or project mismatch · 3 no stored key or account unresolved |
| JSON schema | solwyn.keys-env.v2 |
Related
- Scoped login: API keys, choosing the project, where credentials are stored, and what
fullversusread_onlyallows projects create: create a project and its first key- Dashboard: API keys: the same keys in the browser, plus adding a project to a key
- Scripting: JSON envelopes and the exit-code contract