API keys that act as their owner, and never more

On 13 October we added a way for other apps and tools to use genvi. To do that, you make an API key. An API key is a password that lets another app use your account. The big question was what a key should be allowed to do. Our answer: a key acts as its owner, only narrower. It can do what you can do, under the same rules, and nothing more.

The easy way to build this is to give every key a master pass to the whole system. We chose not to. Most things in genvi already check who is asking: your projects, your library, your files. A master pass would skip all of those checks. Every part of the system would then need its own extra rules about who may see what, and one missed rule would be a leak.

Instead, a key signs in as you, the same way you do. So all your normal rules apply. If an account is being deleted or has been banned, its keys stop working too. There is no second list of rules to forget about.

Signing in again on every request would be slow. Storing a ready-made sign-in in plain text would be risky, because anyone who got a copy of our data could use it. So we lock each sign-in with a secret that comes from your API key itself.

We only see your key while we are answering a request that carries it. So only that request can unlock the sign-in. A stolen copy of our data opens nothing. Checks confirm that the lock only opens with the right key, and that a sign-in about to run out is never used.

Turning off a key takes effect at once. We check that the key is still active on every request. A key whose owner can no longer sign in is simply treated as invalid.

Each key has a short list of things it may do. There are seven: account, models, projects, library, reading generations, making generations, and the genvi agent. When you make a key, you choose a purpose instead of a list: Full access, Generate, or Read only. New keys start on Generate, with a limit of 500 credits a day and a life of 90 days.

Every action checks the key's permissions, and then checks again further down. The repeat is on purpose. If one part forgets to check, the next one still stops the key from doing too much. Changing a key's permissions takes effect on the very next request.

Some things are not on the developer side at all: billing, your account details, workspaces, managing keys, and the admin tools. No key can reach them, so there is no permission that could be handed out by mistake.

If a key leaks, the real danger is spending. So every key has a daily credit limit. Before each run, we set the credits aside and check the limit in a single step. That means 30 requests sent at the same moment cannot all slip past the limit. If a run does not use the credits, they are returned.

You can swap a key for a new one and keep the old one working for a short time (0, 1, 24 or 168 hours). You can turn off all your keys at once. Our team can also turn off a key during an incident, and every one of these actions is recorded.

The steps of a generation used to live only in the website. These steps include checking the request, recording the job, keeping it alive, and giving credits back if you cancel. When we added the developer tools, we did not copy them. We moved them into one shared place, so the website and the API run the very same steps.

The website shows live progress. The API gives you a job number and lets the work finish in the background. You can ask for the result later. API jobs share the same rate limit as the website. A rate limit is how many requests you can send in a short time. So the API adds no extra room for bursts. A key cannot read your canvas jobs.

Automatic tests check the key format and the permissions. They also check that key swapping works, and that every developer action needs a key while no other part of genvi accepts one. Another test confirms that a key with no active record is refused every time, even if we remember it from before.

To use it, make a key on your Account page. Pick the narrowest option that does the job, and read the developer docs.