Make an API token
Make a token so one of your programs can drive a workspace, choose its role, and revoke it when you are done.
Make a tokenA secret a program of yours uses to drive a workspace, with one role.Glossary → when a program of yours should drive a workspace: a dashboard, a script, an orchestrator.
Paste this into your coding agent to make an API token at the right role and keep it out of chat and git.
Show the prompt
Make a Hivemind API token for one of my programs, at the smallest role it needs, and store it safely. 1. Ask me what the program is called, which workspace folder it drives, and what it does. Choose the role from that: `view` only reads; `edit` also presses widgets and opens tool tiles; `terminals` also types into terminals; `agents` also starts, answers and closes agents. Tell me the role you chose and why. 2. Check Hivemind runs with that folder open: `hive ctl agents` must not exit 3. If it does, ask me to open the folder with `hivemind <folder>`. 3. Make it, with an expiry unless I ask otherwise: `hive grant create <name> -w <folder> --role <role> --expires 30d --json`. The output holds `token` (shown only this once) and `socket`. 4. Never show the token in this chat and never put it in a file git tracks. Write it to a git-ignored `.env` beside the program as `HIVE_DRIVE_TOKEN=…`, with `HIVE_DRIVE_SOCK=<socket>` and `HIVE_WORKSPACE=<folder>`. Check `git check-ignore .env` confirms it is ignored; add it to `.gitignore` if not. 5. Check it works: with those variables loaded, `hive ctl agents --json` prints the workspace's agents. At the end, tell me the token's id and role from `hive grant list`, where the token is stored, and that `hive grant revoke <id>` takes it back. REFERENCE https://hivemind.griiken.com/guide/api-tokens.md
Before you start
- Hivemind is running with the workspace open, or
hive hostserves it. - You know what the program does, so you can pick the smallest role. See Choose a role.
Make the token
Open API access
Open the workspace, then Settings → API access.
Name it and pick a role
Under New token, name what uses it, for example my dashboard. Pick what it may do.
Create and copy
Press Create token, then Copy. The token is shown this once.
A token made in Settings reaches the workspace in that window and never expires.
Hivemind keeps only a hash of each token. A lost token cannot be shown again, so make a new one.

Choose a role
Each role can do everything the roles above it can. People and programs get the same four roles.
| Role | For a person, the app says | For a token, API access says | Can |
|---|---|---|---|
view | Can view | View | see the canvas, terminals, agents and their replies, files, diffs, issues and review comments |
edit | Can edit board | Edit | also move, add and close tiles, press widgets, open a tool's tile |
terminals | Can use terminals | Use terminals | also type into terminals (a person once given the keyboard) |
agents | Can drive agents | Drive agents | also start, answer, message, put to sleep and close agents, which means running commands on your computer. A person gets it only while they are here, after a warning. |
A dashboard needs view; an orchestrator that starts agents needs agents. A call the role does not allow is answered FORBIDDEN and never runs. The full list is on Methods by role.
Check it worked
To see your tokens, run:
hive grant list1a2b3c4d5e6f dashboard view /home/you/work/api expires 2026-11-17T09:00:00Z last used neverSettings → API access shows the same list, with when each token was last used.
Revoke a token
Press Revoke in Settings → API access, or run it with the id from hive grant list:
hive grant revoke 1a2b3c4d5e6fRevoking closes the program's connections at once. An expired token closes them at that moment too.
If it didn't work
| What you see | Fix |
|---|---|
hive ctl exits 3 | Neither the app nor hive host is running. Open the workspace with hivemind <folder>. |
FORBIDDEN on hello | The token is wrong, revoked or expired, or does not reach that workspace. Make a new one. |
BAD_REQUEST on hello | Name the workspace's folder, and open it in the app first. |
More in Troubleshooting.
Related
- API overview: how tokens and roles fit together.
- Connect and call: use the token from a program.
Last validated for Hivemind 2026.10.3.
API overview
Let a program of your own drive a workspace: start agents, read their replies, follow who is waiting, all with a token you can revoke.
Connect and call
Build a small client with the TypeScript or Python SDK: connect with your token, start an agent, read its reply, answer it, and hear events.