API keys
Give a script a key that reaches one Safe's workflows, and nothing else.
What it does
An API key lets code reach a Safe's workflows without a signed-in wallet. A script can list the workflows, read one, see its runs, read its automation permission, and ask for a run to send.
A key belongs to one Safe, on every chain the Safe is on, and to its workflows only. It can't read the Safe's assets, propose or sign anything, save a workflow, or make another key. It never sends a run itself: a run key your code holds does. Every other request with a key is refused.
A key can also ask Tamias for a run of an automated workflow, which your code then sends from its own wallet. That is Run a workflow from code.
Making a key
Open the Safe's Settings → API keys. Only an admin of the Safe's organization sees it.
- Press Create a key and name it after what will use it, e.g. "Health-factor bot".
- Copy the key. It starts with
tamias_. It is shown once. Tamias stores a hash of it, never the key, so it can't be shown again. If you lose it, make a new one and revoke the old one. - Copy the Safe id for the chain your script works on. It is listed on the same page, one per chain.
The list shows each key's name, its first characters (tamias_KrZhM…), who
made it, and when it was last used.
Calling the API
Send the key as a bearer token to https://api.tamias.io:
curl https://api.tamias.io/safes/<safe id>/workflows \
-H "Authorization: Bearer tamias_…"The <safe id> is the id from the API keys page, not the Safe's address. A
Safe on three chains has three ids, one per chain, and each one returns the
workflows recorded on that chain.
| Request | What it returns |
|---|---|
GET /safes/<safe id>/workflows | Every workflow on the Safe on that chain, newest first |
GET /safes/<safe id>/workflows/<workflow id> | One workflow: its name, its steps, and the calls it makes |
GET /safes/<safe id>/workflows/<workflow id>/runs | Its runs, newest first, each with its transaction and status |
GET /safes/<safe id>/workflows/<workflow id>/permission | Whether it is automated, for whom, with what limits, and until when |
GET /safes/<safe id>/workflow-permissions | Every workflow on the Safe that runs without signatures |
POST /v1/workflows/<workflow id>/run | A run of an automated workflow, ready for your run key to send. See Run a workflow from code |
POST /v1/workflows/<workflow id>/runs | Records a run you sent, so it lists under the workflow |
The two /v1/ routes name only the workflow: the key already says which Safe.
A workflow's id is the last part of its address in the app:
app.tamias.io/safe/0x…/workflows/<workflow id>.
When it is refused
| Status | Why |
|---|---|
401 invalid API key | The key is wrong, or it was revoked, or the Safe was removed from the organization. |
403 forbidden | The key is for a different Safe than the one in the URL. |
403 an API key reaches only its Safe's workflows | The request is for something a key can't reach. |
Revoking a key
Press Revoke next to it and confirm. Code using the key is refused on its next request. A revoked key can't be brought back; make a new one.
Removing the Safe from its organization stops all of its keys too.
What the activity log shows
Making a key, revoking it and using it all appear in the organization's activity log:
- "created the API key “Health-factor bot” (tamias_KrZhM…) for this Safe's workflows", with who made it.
- "revoked the API key …", with who revoked it.
- "the API key … was used", once per key per day (UTC), not once per request. A script that polls every minute would otherwise fill the log.
Keeping a key safe
- Treat it like a password. Keep it in your script's secret store or environment, never in code you commit.
- Make one key per script. Then revoking one doesn't stop the others, and the log says which one was used.
- Revoke a key you no longer use. A Safe can hold ten at most.