Authentication and scopes
Bearer keys, the ikr_ prefix, read and generate — and how to make a key.
A key is a bearer token. It is stored only as a hash — Ikrames cannot show it to you again, so keep it the way you would keep a password, out of source control and out of chat logs.
There are two scopes:
| Scope | Tools |
|---|---|
read | list_brands, get_costs, get_asset, list_leads, get_lead |
generate | generate_image, create_composition |
A read key does not see the generate tools at all. They are not registered for it: they are absent from tools/list, and calling one returns "Tool generate_image not found" — not "forbidden". That wording is deliberate. An error that distinguishes "exists but you may not" from "does not exist" tells an unauthorised caller what to go looking for.
Rejected keys all get the same answer, for the same reason: an unknown key, a revoked key, and a malformed header each return 401 with no detail. The real reason goes to the server log.
Keys can be revoked. A revoked key stops working immediately, on the next request — there is no cache to wait out.
Getting a key
You create one yourself, in the app. Open the account menu behind your avatar and pick API-Schlüssel — it sits next to Einstellungen, not inside it. (The app runs in German or English; the German labels are quoted here because the German build is the one most Ikrames accounts use. In English the entry reads API keys.)
Creating a key asks for two things:
- A name, up to 60 characters. It is for you, not for the server — it is what you read months later when you are deciding which of five keys is safe to kill. Name it after whatever will hold it (
Architekt MCP,laptop,n8n), not after what it does. - The scopes it gets:
read,generate, or both. The table above says what each one unlocks.
The key itself is shown exactly once.
It appears in the answer to that one create action and nowhere else. Only a hash is stored, so the app cannot show it again and nobody at Ikrames can look it up for you — there is no "reveal" and no support path. Copy it into your config right then. From that moment the list shows only the last four characters, which exist so you can tell two keys apart and are good for nothing else. Lost the value? Create a new key and revoke the old one.
Every key starts with ikr_. The prefix is deliberate: a string that turns up in a log file, a screenshot, or a pasted config is recognisable as an Ikrames key at a glance, and a secret nobody can identify is a secret nobody revokes.
Scopes are fixed for the life of a key. There is no edit, on purpose — a read key never grows into a generate key. An agent that needs more gets a new key, and the old one goes away. A permission that can widen after the token is already in circulation is not a permission, it is a request.
Revoking is final. It bites on the next request, as above, and it cannot be undone; revoking twice does not move the timestamp either, because when a key died is the fact an incident review leans on. The row stays, so a revoked key keeps showing in the list below the live ones, with the time it was last used.
Creating and revoking take a management role — workspace owner or admin. Using a key does not: a key is bound to the workspace, never to the person who made it, and it keeps working after that person leaves.
A key belongs to the workspace, not to a brand. It sees every brand in that workspace, list_brands hands back all of them, and there is no way to narrow a key to one of them. If your agent may only touch a single brand, that boundary lives in your code — in the brand_id you pass — and not in the key.
How many keys you may hold at once is part of your plan:
| Plan | Active keys |
|---|---|
| Free | 1 |
| Creator | 3 |
| Pro | 10 |
| Studio | 25 |
| Studio+ | 50 |
The ceiling counts active keys per workspace; revoked ones do not count, so tidying up never costs you a slot. Watch the order when you are sitting on the ceiling, though: there you have to revoke first and create second, so the comfortable rotation — make the new key, move the config over, then kill the old one — is not available on the last free slot. Rotate a key that something depends on with that gap planned in.