Voxta API keys
What an API key may do, how to give an app only what it needs, and what older keys can do after upgrading.
An API key lets a program act as your account without your password — the VAM plugin, Voxy, a Discord bot, your own scripts. Each key carries scopes: the list of things it may do. A key made for a chat bridge does not also get to edit every character you own.
Creating a key
Profile menu → API keys → Create. Name it after the client, then tick what it may do.
A new key starts with Chats ticked and nothing else. Everything beyond that is a choice you make on purpose. The key is shown once, when it is created — copy it then.
One key per client, so you can delete one without breaking the rest.
Scopes
| Shown as | Scope | What it allows |
|---|---|---|
| Chats | chat | Start, read and delete this account's chats, send messages, and use the generation services. |
| Inference | inference | The OpenAI-compatible endpoints and the Decisions API. Nothing else. |
| Edit resources | resources.write | Create, edit, import and delete characters, scenarios, memory books, collections and packages. |
| Observe chats | sessions.read | Watch this account's other open chats, audio included. |
| Drive chats | sessions.write | Send messages into this account's other open chats. |
| Answer tool prompts | tools.write | Answer tool permission prompts for anything short of destructive, and switch between Ask, Plan and Allow Edits. |
| Allow destructive tools | tools.dangerous | Answer destructive prompts, choose Allow All, and give a chat a working folder, the shell and the disk tools. |
The last two are marked dangerous and listed last. A key without either cannot answer a tool prompt at all — a person has to.
Allow destructive tools reaches the machine, so it is held to the same bar as an administrator doing it in person. It is only offered on an administrator account with a password, it includes Answer tool prompts, and it only works for a client connecting from the machine the server runs on.
Apps that ask for a key
Some apps sign in with a code instead of a pasted key: they show a code, you enter it on Voxta's device page and approve. The approval screen lists the scopes the app asked for. You can untick any of them. Scopes your account cannot grant are shown greyed out with the reason, so the app does not find out at its first refused request. You can take scopes away; you cannot add ones the app did not ask for.
Keys made before 1.11
Older keys keep working, unchanged. They were issued one of three roles, which now read as:
| Old key | Now holds |
|---|---|
role:app | Chats, Inference, Edit resources, Observe chats, Drive chats |
role:provider | Observe chats, Drive chats |
role:inspector | Observe chats |
No old key gets a tool scope. Nobody agreed to hand an app the shell when those keys were made. To let a client answer tool prompts, create a new key with that scope.
A scope this version does not know is ignored rather than breaking the key, so a key made by a newer Voxta still works for everything both versions understand.
Keys and encryption
A key issued before you turned on encryption, or before your last key rotation, cannot read your content. The API keys page flags it. Delete it and create a new one.