Aetherfy API keys

The format of an Aetherfy API key

An Aetherfy API key is a prefix followed by exactly 32 hexadecimal characters.

The prefix is a record of which Aetherfy environment issued the key, not a mode you select. There is no control that mints a test key, and one is not a sandbox against your production account: each prefix binds the key to the environment that created it, and Aetherfy never falls back from one to the other. Keys you create yourself are afy_live_ keys.

Aetherfy stores only a SHA-256 hash of the key. It also keeps a display-only prefix — the first 12 characters — so you can identify a key in a list without the plaintext existing anywhere in the system.

That 32-hexadecimal shape is what Aetherfy generates. The client-side validators are deliberately more permissive than the generator, so they keep working if the issued format ever widens — neither is a statement about what Aetherfy issues today:

• The Aetherfy generator issues afy_live_ or afy_test_ followed by exactly 32 hexadecimal characters. This is the canonical, issued format.
• Both Aetherfy SDKs validate against ^afy_(live|test)_[a-zA-Z0-9]{16,}$ — 16 or more alphanumeric characters, not necessarily hexadecimal.
• The Aetherfy CLI requires the prefix plus at least 32 alphanumeric characters.

A key that passes an SDK or CLI check is therefore not necessarily a key Aetherfy issued; only the server decides that. The looser client-side rules exist so an older SDK or CLI does not reject a future key format.

The one-time reveal of an Aetherfy key

The plaintext of an Aetherfy API key is shown exactly once, at creation, and never again. There is no endpoint that returns it afterwards, and Aetherfy support cannot recover it, because only the hash was kept.

On first login the Aetherfy welcome modal reveals your default key’s plaintext once. A second attempt at that reveal returns HTTP 410 with the code ALREADY_REVEALED. If you lose the plaintext, the answer is always to create a new key.

Where to manage Aetherfy API keys

Create, rename and revoke keys at https://app.aetherfy.com/dashboard/settings/api-keys .

Revoking a key in Aetherfy takes effect immediately — there is no propagation delay and no grace window for in-flight clients.

What an Aetherfy API key is scoped to

Aetherfy API keys are per account. They are not per workspace and not per project. Holding one key rather than another does not narrow what you can reach.

Tenant isolation in Aetherfy is enforced per request on the server, derived from the account the key belongs to — not by the key carrying a scope of its own.

Agent-scoped keys issued by Aetherfy

An Aetherfy agent receives an automatically-generated key, injected into its environment as AETHERFY_API_KEY. These keys behave differently from the ones you create:

You do not create, rotate or revoke these yourself.

The injected key is bound to the deployment that is running, so a version that has been superseded cannot use the vector database or the agents API any more. Replacing a service deployment replaces its keys, and a task run’s key stops working when the run finishes.

“Agent-scoped” describes that lifecycle, not a narrower permission. The injected key is an ordinary key on your account: it is bound to one agent and one of its deployments in the sense that Aetherfy issues, rotates and deletes it alongside them, but it reaches everything your account reaches. Aetherfy has no mechanism for a key that reads less than the whole account — see the scoping section above — so treat the code you deploy to an agent as code you have handed an account credential.

How many API keys each Aetherfy plan allows

Exceeding the limit returns HTTP 400 from Aetherfy, with a message naming your plan and its allowance. Agent-injected keys are excluded from this count.

Rotating an Aetherfy API key

There is no rotate endpoint in Aetherfy. Rotation is a three-step procedure you perform yourself:

1. Create a new key at https://app.aetherfy.com/dashboard/settings/api-keys  and capture the plaintext at creation time.
2. Update every client, environment variable and secret store that carries the old key.
3. Revoke the old key.

Do the steps in that order. Revocation is immediate, so revoking before step 2 is complete will break live traffic.

How Aetherfy clients read the key

Both Aetherfy SDKs check the environment in that order, so setting AETHERFY_API_KEY covers every client at once. The CLI is documented at the Aetherfy CLI.

Authenticating directly against the Aetherfy HTTP API

Send the key as a bearer token:

Authorization: Bearer afy_live_0123456789abcdef0123456789abcdef

Aetherfy answers a bad or absent credential with:

Both are terminal for the request — retrying the same key will not change the answer. The two codes are the same on both Aetherfy surfaces, since the same key authenticates both; only the envelope differs, error.code on the vector API and detail.code on the control plane.