Gateway API Keys
How Athena gateway API keys are created, stored, scoped, enforced, and locked down.
Athena gateway API keys are the credentials that authorize runtime gateway,
management, storage, and RPC calls. They are implemented in src/api/admin/mod.rs,
src/data/api_keys.rs, src/data/api_key_ips.rs, src/api/auth.rs, and
src/api/gateway/auth.rs.
If you have heard these described as "version keys", Athena does not currently
have a separate key type by that name. The lock-while-learning feature in the
codebase is called virgin_mode, so this section documents the implementation
using Athena's real field names.
What this section covers
- The plaintext credential format
ath_{public_id}.{secret}and why only part of it is stored. - How
ApiKeyRecordmetadata, right grants, client binding, and expiration are enforced on each request. - What per-key and global IP rules do, how
ApiKeyIpPolicyis evaluated, and howapi_key_ip_seensupports lock-in. - How
gateway.auth_client,gateway.api_key_fail_mode, andget_effective_api_key_enforcementdecide whether a route requires a key. - Full admin and caller flows, with concrete
curlexamples and links into the generated API reference.
Mental model
Two important boundaries:
- Admin lifecycle routes under
/admin/api-keys*,/admin/api-key-rights*, and/admin/ip-global-*are controlled byATHENA_KEY_12, not by gateway API keys. - Runtime routes use gateway keys presented through
X-Athena-Key, then evaluate client binding, rights, and IP policy before allowing the request.
Reading path
Format and Lifecycle
Rights and Client Binding
Whitelists and Blacklists
Virgin Keys and Lock-In
Enforcement and Fail Modes
Implementation Recipes
Troubleshooting
Quick facts
| Topic | Current Athena behavior |
|---|---|
| Plaintext key shape | ath_{public_id}.{secret} |
| Runtime header | X-Athena-Key |
| Static admin headers | X-Athena-Key or X-Athena-Admin-Key |
| Admin lifecycle auth | ATHENA_KEY_12 |
| Runtime store | gateway.auth_client, falling back to gateway.logging_client |
| Default fail mode | fail_closed |
| IP rule precedence | global blacklist -> per-key blacklist -> unresolved virgin learning -> global whitelist -> per-key whitelist |
| Lock-in feature name | virgin_mode |