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 token 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 host serves 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.

Settings → API access: the New token form with a name, a role menu set to Drive agents, and Create token; the Tokens list is empty.
Settings → API access

Choose a role

Each role can do everything the roles above it can. People and programs get the same four roles.

RoleFor a person, the app saysFor a token, API access saysCan
viewCan viewViewsee the canvas, terminals, agents and their replies, files, diffs, issues and review comments
editCan edit boardEditalso move, add and close tiles, press widgets, open a tool's tile
terminalsCan use terminalsUse terminalsalso type into terminals (a person once given the keyboard)
agentsCan drive agentsDrive agentsalso 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 list
1a2b3c4d5e6f  dashboard  view  /home/you/work/api  expires 2026-11-17T09:00:00Z  last used never

Settings → 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 1a2b3c4d5e6f

Revoking closes the program's connections at once. An expired token closes them at that moment too.

If it didn't work

What you seeFix
hive ctl exits 3Neither the app nor hive host is running. Open the workspace with hivemind <folder>.
FORBIDDEN on helloThe token is wrong, revoked or expired, or does not reach that workspace. Make a new one.
BAD_REQUEST on helloName the workspace's folder, and open it in the app first.

More in Troubleshooting.

Last validated for Hivemind 2026.10.3.

Edit on GitHub

On this page