Authentication

Make a key

Open Settings, then API keys. Give the key a name that says where it will be used, then create it.

The key is shown once. Copy it straight away and keep it somewhere safe, such as your server's environment variables. Setherion stores only a fingerprint of it, so nobody can show it to you again, us included. If you lose it, revoke it and make a new one.

A key starts with sth_, followed by 43 random letters, digits, - and _, 47 characters in all. The name can be up to 60 characters; a longer one is cut.

Send it with every request

Put the key in the Authorization header:

curl https://www.setherion.com/api/v1/projects \
  -H "Authorization: Bearer $SETHERION_API_KEY"

const res = await fetch('https://www.setherion.com/api/v1/projects', {
  headers: { Authorization: `Bearer ${process.env.SETHERION_API_KEY}` },
})
const data = await res.json()

Only the Bearer scheme is read. A request without a valid key gets 401:

{
  "ok": false,
  "error": "A valid API key is required. Make one on your Setherion account page and send it as \"Authorization: Bearer sth_...\"."
}

A missing header, a key that is misspelt, one that does not exist and one that was revoked all get this same answer, so it never tells you which of them it was.

What a key can do

A key acts as you. It can do what you can do in Setherion:

• see the apps on your dashboard, your own and the ones shared with you;
• read the app store guide and privacy answers of any app you can open;
• change the apps you can edit, spending credits the way an edit in the editor does;
• publish the apps you can edit, and write their store page.

Your role on each app decides the rest. A call that reads needs viewer or more; a call that changes an app or spends credits needs editor or more. See Introduction for which call needs which.

A key cannot change your account, your plan or your billing, and it cannot make or revoke keys: that is only possible when you are signed in to Setherion yourself, so one leaked key can never mint others.

Revoke a key

In API keys, press Revoke next to the key. It stops working at once. Revoked keys stay in the list so you can see when they were last used.

You can have up to 10 active keys at a time. Asking for an 11th is refused with You have 10 active keys. Revoke one you no longer use to make another. The list shows when each key was last used, updated at most once a minute.

Signing in without a key

AI assistants connect with a sign-in page and an Allow button instead of a key. See Connect an AI assistant.

The tokens that sign-in produces work on the assistant address (/api/mcp) only. The endpoints in this reference take an API key and nothing else.