API keys and security
A Director API key is how your own code signs in to the hosted Director. This page covers creating one, keeping it safe, and what to do when it leaks.
What a key is
- A key belongs to your Eposyne account and starts with
epd_. - It works only on the hosted Director at
https://director.eposyne.com. It does nothing on Architect or anywhere else. - Every decision a key makes is paid from your account's usage credits. Anyone who holds the key can spend them.
- A key cannot create, list, or revoke keys. You manage keys by signing in to your account.
Create a key
- Sign in at architect.eposyne.com.
- Open https://architect.eposyne.com/profile?section=director-keys.
- Give the key a name that says where it runs, such as
staging-serverormy-laptop. - Copy the key when it is shown. It is shown once. Eposyne stores only a hash of it and cannot show it again. If you lose it, create a new one.
The hosted Director serves keys of accounts on Pro and higher. A key of a Free or Starter account is refused with 403 feature_not_in_plan, see Errors. You can have up to 10 active keys. Use one key per server or per tool, so you can revoke one without disturbing the others.
Use a key
Authorization: Bearer epd_your_key_hereRead it from an environment variable or a secret store at startup. Do not write it into source code or commit it to a repository.
Where a key may live
A key belongs on a server or on a developer machine. Never put it in a game build that players download, and never in a web page.
Anything inside a build or a page can be extracted by the people who receive it. A key found there is a key anyone can spend. The hosted Director is a beta for building and testing, and a shipped game cannot use it yet.
| Place | OK? |
|---|---|
| Your backend server, from an environment variable or secret store | Yes |
| Your own machine, for scripts and tests | Yes |
| A CI job, as a secret | Yes |
| A game build or installer players download | No |
| A web page, a browser script, or a mobile app | No |
| A public repository, a log, or a chat message | No |
Browsers cannot call Director
Director sends no CORS headers, so a web page cannot call it from the browser. This is deliberate: a call from a page would need the key in the page. If your product has a web front end, let the page call your own backend, and let your backend call Director with the key. Your backend is also the place to add your own checks, limits, and per-player rules.
Browser --> your backend --> Director
(holds the key)Revoke a key
Open the keys page, find the key by its name, and revoke it. The key stops working within 60 seconds. Director checks keys with the account service and keeps an answer for up to a minute, so a revoked key may work for that long. After that every call with it gets a 401.
Replace a key
There is no rotation flow. To replace a key: create a new one, deploy it, check that the new key works, then revoke the old one.
If a key leaks
- Revoke the key at once.
- Create a new key and deploy it.
- Check
GET /v2/usage/meand your credits page for spend you do not recognize.
The damage is limited by your credit balance, the balance floor of EUR 1.00, and the monthly limit you set. See Billing and limits. Set the monthly limit to an amount you are comfortable losing.
When the account service is down
Director asks the account service to confirm a key it has not seen in the last minute. If the account service cannot be reached, a key that is not in Director's short memory gets a 503 with "code": "account_service_unavailable", not a 401. Retry with backoff.
Keys and sign-in are different
The Eposyne engine plugins and the Director console sign you in through your browser and use short-lived tokens. You do not need a key for them. A key is for code you write yourself: a game server, a script, a tool.