API keys

An API key lets a program work on your behalf: a script that opens an order when a form on your own website is filled in, a dashboard that counts this month's jobs, a tool you write yourself.

If you do not write software and nobody is writing any for you, there is no reason to create one. Nothing in Kalepio needs a key.

Where they live

Under Settings, API keys. In your personal settings rather than the studio's, because a key belongs to you: you made it, and it leaves your studios when you do.

One key, one studio

You choose the studio a key will work in when you create it. It can never do anything anywhere else, even if you belong to ten other studios.

That is what makes a key reasonable to hand over: if it ends up in the wrong hands, what is at stake is one workshop rather than all of your work.

A key never does more than you

The most important rule on that screen, and it has two halves.

You can only give away rights you already hold. The screen offers those and no others: if your studio does not let you handle payments, the box is not there. That is not an oversight, it is the only thing the key could ever have done anyway.

And it follows your rights over time. The day your studio takes a right away from you, the key loses it too, with nobody having to remember. The day you leave that studio, it stops working entirely.

"Everything I can do", or a list

Two ways of deciding what a key will be able to do.

Everything I can do is ticked by default, and it is what you want for your own tools. The key does exactly what you already do from your dashboard, and it stays in step: a right granted to you later, it gains too.

A list, ticked by hand, when you are handing the key to somebody else or to a program you did not write. A key that only knows how to read orders cannot delete one, even though you can.

The key is shown once

At creation, in a dialog, with a button to copy it. Put it straight into a password manager.

After that it cannot be shown again. We keep only a fingerprint of it, as with a password: there is no way to recover it, for you or for us. If you lose it, revoke it and make another.

That is also why the name you give it matters: it is the only way to tell the right one apart when the list holds four.

Revoking a key

One click, and it stops working immediately. Any program still using it gets an error on its next request.

Do it without hesitating as soon as a key has been copied somewhere it should not have reached: a screenshot, a message, a shared configuration file. Making a new one takes ten seconds.

What the list does not show

The date a key was last used. Kalepio does not keep it, and its absence is not a bug: it is information we chose not to store.

For whoever is going to use it

The API's address, the requests it accepts, the filters and the error codes are in the API reference, which is written in English because it is read beside class names and HTTP status codes.

The first call to make is always the same one: it says which studio the key belongs to and exactly what it may do there.