API keys: make one, choose its workspaces, revoke it
Make an API key for your own code, choose which workspaces it can touch, send it with each request, and revoke it when you stop using it. Your AI agent does not need a key.
Steps
Step 1 Know when you need a key
An API key is for your own code: a script, a server or an automation tool that calls the uplika REST API. It acts for your account, so keep it as you would a password.
An AI agent such as Claude or ChatGPT does not use a key. It connects on the MCP screen and you approve it in your browser.
Step 2 Create a key and set its permission
Open API Keys in the dashboard sidebar and click Create key. Name the key after the place that will hold it, such as the server or the tool, so you can tell your keys apart later.
Under Permission, Read & write can publish. Read only can only look things up, and a call that publishes comes back with forbidden_scope. Pick Read only when the code only reads.
Step 3 Choose which workspaces the key can touch
With more than one workspace, the dialog asks "Which workspaces can this key touch?" The workspaces picked at the top of the API Keys screen start checked. If you were viewing all of them, your first workspace is checked. Check each workspace this code works with.
All workspaces reaches every workspace you have now and every one you add later. The dialog says so when you check it. A key with chosen workspaces stays on those, and a workspace you add later is outside it.
With one workspace there is nothing to choose: the key covers that workspace only. After you add a second workspace, make a new key for it.
You cannot change a key's workspaces or permission afterwards. Make a new key and revoke the old one.
Step 4 Copy the key before you close the window
This value is shown only now. We do not store it either. Click the copy button next to it. Close stays off until you do.
If your browser blocks copying, a box appears under the key. Copy the key by hand, then check that box to close the window.
Keep the key where your code reads secrets, such as an environment variable or a secret manager. Do not paste it into a chat, a shared document or a commit. If you lose it, there is no way to see it again, so make a new one.
Step 5 Send the key with each request
Put the key in the Authorization header of every request, after the word Bearer. The headers are shown below.
If the key covers one workspace, that is all. If it covers more than one, also send the x-uplika-workspace header with the id of the workspace the request is for. Without it the request comes back with workspace_required and a list of the key's workspaces with their ids, so you can copy the id from there.
To see what a key did, open Logs. The Via column shows API key and the key's name. On API Keys, the Last used column shows when each key was last used.
Step 6 Revoke a key you no longer use
On API Keys, open the menu at the end of the key's row and choose Revoke key. Type the key's name and click Revoke. Every request using this key fails with 401 immediately. This cannot be undone.
Revoke a key right away if it may have leaked, then make a new one and put it where the old one was. A revoked key stays in the list as Revoked.
Headers to send
Authorization: Bearer <your key> x-uplika-workspace: <workspace id>
Errors you may see
| Code | What it means | What to do |
|---|---|---|
| invalid_api_key | The key is missing, mistyped or cut short. | Copy the whole key again, or make a new one. |
| api_key_revoked | This key was revoked in the dashboard. | Make a new key and use it instead. |
| forbidden_scope | A read-only key tried to publish or change something. | Make a key that can read and write. |
| workspace_required | The key covers more than one workspace and the request did not say which, or it named a workspace outside the key. | Send the id of a workspace from the list in the error. |
If you get stuck
Try it on your own accounts
Connect a channel, add uplika to the agent you already use, and ask it to post. No card to start.
Sign up