What a key looks like
A key starts with esi_dev_ and continues with 43 characters of URL safe random data.
esi_dev_T2tFc3ZhZXNpRGV2QXBpS2V5RXhhbXBsZUZvcmxhaXNThe first eight characters after the prefix are how the console identifies the key in a list, so you can tell two keys apart without either of them being visible. The rest is never stored in a form anyone can read, including us. Keys are hashed at rest, and you see the whole thing exactly once, at the moment you create it.
That is not an inconvenience to work around. If we could show you a key again, we could also be compelled to show it to someone else.
Using it
Send it as a bearer token on every request.
Authorization: Bearer esi_dev_YOUR_KEYThe scheme is checked strictly. Bearer is accepted, and so is lowercase bearer, but a bare key with no scheme in front of it is rejected. This is the most common reason a first request comes back as 401 when the key itself is fine.
Never put a key in anything that runs in a browser or ships to a device. Anything sent to a client can be read by whoever holds that client. Call EvaEsi from your own server and let your users talk to that instead.
Keys are for your code. The console uses a browser session instead, which is a separate thing entirely and is what you will sign into when the console opens.
Scopes
A key carries a scope that decides what it may reach. Give a key the narrowest scope that lets it do its job, so that if it leaks, the damage is bounded by something other than luck.
| Scope | What it opens |
|---|---|
inference | The public inference routes such as /api/v1/responses. This is what most keys should be. |
platform | Reserved for platform APIs. It grants no inference access at all, so a key with only this scope cannot spend anything. |
full | Both of the above. |
Managing keys
Keys are created and revoked in the console, on session routes rather than with a key. That is deliberate: a key cannot mint another key, so a leaked key cannot be used to grow itself a foothold.
| What you want | Endpoint |
|---|---|
| Create a key | POST /v1/auth/api-keys |
| List your keys | GET /v1/auth/api-keys |
| Rotate one | POST /v1/auth/api-keys/{id}/rotate |
| Revoke one | DELETE /v1/auth/api-keys/{id} |
| See what it has been doing | GET /v1/auth/api-keys/{id}/usage |
You can hold five active keys at once. New keys attach to your default developer project unless you say otherwise when creating them. Set an expiry on anything temporary, because a key with an end date is one fewer thing to remember to clean up.
Rotation
Rotating gives you the new key straight away and marks the old one for revocation twenty four hours later. Both work during that window.
The overlap exists so you can deploy without a gap. Take the new key, roll it out everywhere, confirm traffic has moved, and let the old one lapse. If you are rotating because a key leaked, do not use the grace period. Revoke it outright and accept the brief outage.
If a key leaks
Revoke it first. Not after you have worked out how it happened, and not after you have prepared a replacement. Revoke it, then investigate, then replace it. The window where a key is both public and live is the only part of this you control.
Then check GET /v1/auth/api-keys/{id}/usage for what the key did while it was out, and your usage records for spending you do not recognise. A budget cap limits what a leaked key can cost you, which is a good reason to set one before you need it.