Authentication & API keys

Aethis uses a single API key per identity. What the key can do is governed by its scopes — not by your account role. This page is the one place that explains the scope model, so a permission error is a lookup, not a surprise.

Do you even need a key?

No — not for evaluation. Public rulesets are discoverable, inspectable, and decidable anonymously:

aethis rulesets list --public
aethis decide -b aethis/uk-fsm/child-eligibility \
  -i '{"child.age": 10, "child.school_type": "state_funded"}'

You need a key for tenant projects, private rulesets, composed rulebooks, and all authoring commands (generate, publish, rulebooks create, …). aethis login runs a browser sign-in and caches a key locally. This is the whole of first-time setup:

aethis login

aethis init runs the same flow for you the first time, so if you’re scaffolding a project you don’t need a separate login step.

No browser? For CI or a headless box, mint a key on a machine that does have a browser (aethis account generate, below), then set AETHIS_API_KEY on the headless host. aethis login needs a browser to complete the OAuth round-trip.

A key from aethis login (and from aethis account generate with no --scope) carries exactly these six scopes:

Scope	Grants
`decide`	Evaluate rulesets and rulebooks
`projects:read`	List and show your authoring projects
`projects:write`	Create, generate into, and archive projects
`rulesets:read`	List and show your tenant rulesets
`rulesets:explain`	Human-readable rule explanations
`rulesets:write`	Author, test, and publish rulesets

That covers project + ruleset authoring end-to-end. It does not include rulebooks:read / rulebooks:write — see the trap below.

`whoami` — check before you hit a 403

aethis whoami prints the identity, tier, scopes, and — the useful part — whether authoring is available on this key:

aethis whoami

Key:         key_3a1b2c…
Tenant:      tenant_9f8e…
Tier:        internal
Scopes:      decide, projects:read, projects:write, rulesets:explain, rulesets:read, rulesets:write
✓ Authoring enabled — you can create and publish rulesets.

Run this first whenever a command returns 403 denied_missing_permission — it tells you which scopes you’re actually carrying.

The rulebook trap (and the fix)

Because a login key omits rulebooks:*, the first aethis rulebooks create or aethis rulebooks activate on a fresh key fails:

403 denied_missing_permission — key is missing scope 'rulebooks:write'

This is not an account-level block — it’s a missing scope. Mint a rulebook-capable key with the full scope list. --scope/-s replaces the default set, so you must list every scope you want, not just the new one:

aethis account generate --name rulebook-authoring \
  -s decide -s projects:read -s projects:write \
  -s rulesets:read -s rulesets:explain -s rulesets:write \
  -s rulebooks:read -s rulebooks:write

Then aethis whoami should show all eight scopes, and rulebook authoring works.

Rotating and adding keys

aethis account generate mints an additional key — for rotation, a second machine, or a narrower scope set. It does not revoke your existing key.

# A second key for a build box, decision-only, named so you can find it later:
aethis account generate --name ci-decide -s decide

# List keys (masked) and revoke one:
aethis account keys
aethis account revoke <key_id>

Flag	Meaning
`--name` / `-n`	Human label for the key (default `cli-generated`)
`--scope` / `-s`	A scope to grant, repeatable. Replaces the default set.
`--tier` / `-t`	Rate-limit tier: `free` (default), `starter`, `pro`
`--no-save`	Print the key but don’t cache it locally

Multiple identities: profiles

If you switch between personas (e.g. an admin key and a dev key), store each as a named profile rather than swapping env vars:

aethis profile add dev --api-key <key>          # or omit to prompt
aethis profile use dev                            # sticky default
aethis --profile admin whoami                     # one-off override
aethis profile list                               # see all + which is active

Pass --profile anonymous to force unsigned mode for a single command.

Where a key is read from (precedence)

For any command, the key is resolved in this order — first hit wins:

--api-key <key> on the command line
AETHIS_API_KEY in the environment
The active profile / cached credentials (keychain)

--base-url (or AETHIS_BASE_URL) selects the server the key is used against; it defaults to the active profile’s base_url, or https://api.aethis.ai.

CI and background jobs (non-interactive)

Automation must never hang on a prompt. Two ambient switches make every command non-interactive:

Variable	Effect
`AETHIS_NONINTERACTIVE`	Truthy (`1`/`true`/`yes`) bypasses every confirmation prompt; destructive commands proceed instead of hanging on `[y/N]`. Prints a one-line notice so it’s never silently active.
`CI`	Same effect when truthy.

Combine with --no-prompt to fail fast rather than fall back to a browser sign-in when no key is cached:

AETHIS_API_KEY=$KEY aethis --no-prompt decide -b aethis/uk-fsm/child-eligibility -i '{...}'

​Do you even need a key?

​Sign in

​What login mints — and the scopes model

​whoami — check before you hit a 403

​The rulebook trap (and the fix)

​Rotating and adding keys

​Multiple identities: profiles

​Where a key is read from (precedence)

​CI and background jobs (non-interactive)

​See also

Do you even need a key?

Sign in

What `login` mints — and the scopes model

`whoami` — check before you hit a 403

The rulebook trap (and the fix)

Rotating and adding keys

Multiple identities: profiles

Where a key is read from (precedence)

CI and background jobs (non-interactive)

See also