API Keys: Create, Protect, Rotate and Revoke
How to get an API key, keep it secret, replace it safely, and what happens when you revoke one.
Creating a key
Keys are created in the API Keys section of /developer. You can have up to 3 active keys at a time. Revoked keys stay in the list for your records but do not count toward that limit.
- 1Open /developer (Dashboard, then Developer API).
- 2In API Keys, type a name if you want one, such as "Production server" or "Test script". Names can be up to 60 characters. If you leave it empty the key is called "Default".
- 3Press Create Key.
- 4A green box shows the full secret key. Press the copy button and store the key somewhere safe, such as your server's secret settings or a password manager.
- 5Press "I saved it: dismiss". The full key is never shown again.
Tip
- If you already have 3 active keys, creating another shows "You can have at most 3 active keys. Revoke one first."
- Lost a key? It cannot be recovered, by you or by us. Create a new one and revoke the old one.
Using a key
Send the key on every request in an Authorization header as a bearer token. Keys start with "be_sk_". The API Keys table shows only the first few characters of each key, so you can tell them apart without exposing them.
The Last used column shows roughly when each key was last used (it updates at most every few minutes), or "Never". It is a quick way to see which keys are still in use before you revoke anything.
Keeping your key secret
A key spends your credits. Treat it like a password.
Tip
- Keep keys on your server. Never put a key inside a website, browser extension or mobile app, because anyone can read it out of the code.
- Do not commit keys to a code repository. Load them from environment settings or a secrets manager.
- Use a separate key for each app or environment. Then you can revoke one without breaking the others, and Last used tells you which one is active.
- Pasting a key into an AI chat or a third-party tool shares it with that service. Rotate the key afterwards if you are not sure where it went.
Rotating a key without downtime
To replace a key, create the new one first, switch your app over, then revoke the old one. Because you can hold up to 3 active keys, both can work at the same time while you switch.
- 1Create a new key and copy it.
- 2Update your app or server to use the new key and deploy that change.
- 3Watch the Last used column. When the new key shows recent use and the old one has stopped, the switch is done.
- 4Revoke the old key.
Revoking a key
Press the bin icon at the end of a key's row and confirm. Revoking takes effect immediately: any request that uses that key fails with invalid_api_key from that moment. It cannot be undone, so create and switch to a replacement first if the key is still in use.
Revoking a key does not cancel renders it already started, and it does not touch your credit balance. Your credits belong to your account, not to a key.
Tip
- If you think a key has leaked, revoke it right away and create a new one. Then check the credit log on /developer for renders you do not recognise, and contact support at /support if you see any.
More from BallEngine
Guides, plans and answers for making your videos.