Manage
API
Automate your workspace with the REST API and API tokens, or connect an AI agent through the MCP server.
API tokens
Owners and admins create tokens under Keys → API tokens:
- Scope: Read only or Read & write
- Expires: after 7, 30 or 90 days (90 by default, the maximum)
- What is it for?: a description, 1 to 100 characters
Tokens start with tsapi- and are shown once. A token only ever acts on the workspace it was created in. Up to 50 per workspace. Actions taken with a token show in the audit log as API token <prefix>.
Making requests
The API lives at /api/v1 on the coordination service. Send the token as a Bearer token:
curl -H "Authorization: Bearer tsapi-xxxxxxxx" \
https://coord.getunderpass.com/api/v1/nodesRequest and response bodies are JSON. Read-only tokens can only make GET requests.
Endpoints
Machines
| Method | Path | Does |
|---|---|---|
GET | /nodes | List machines |
GET | /nodes/{id} | Get a machine |
PATCH | /nodes/{id} | Change name, user (owner) or keyExpiryDisabled |
DELETE | /nodes/{id} | Remove a machine |
POST | /nodes/{id}/approve | Approve a machine waiting for approval |
POST | /nodes/{id}/expire | Expire its key now |
POST | /nodes/{id}/routes | Approve routes: { "approved": ["192.168.1.0/24"] } |
Auth keys
| Method | Path | Does |
|---|---|---|
GET | /keys | List auth keys |
POST | /keys | Create one: { "reusable", "ephemeral", "preApproved", "tags", "expirySeconds" } |
DELETE | /keys/{id} | Revoke one |
Access controls
| Method | Path | Does |
|---|---|---|
GET | /policy | Get the policy |
PUT | /policy | Replace it. Refused if a test fails |
DELETE | /policy | Reset to allow all |
POST | /policy/check | Check a draft policy and its tests without saving |
The policy format is on Access controls. Editing the policy as JSON is only possible through the API; the dashboard edits it rule by rule.
Services and apps
| Method | Path | Does |
|---|---|---|
GET, POST | /services | List, create |
DELETE | /services/{id} | Delete |
POST, DELETE | /services/{id}/hosts/{node} | Approve or pause a host, remove a host |
GET, POST | /apps | List, create: { "name", "domains", "connectors" } |
PUT, DELETE | /apps/{id} | Update, delete |
Settings, DNS and logs
| Method | Path | Does |
|---|---|---|
GET, PATCH | /settings | keyExpiryDays, keyExpiryOff, deviceApproval, networkLogs |
GET, PUT | /dns | DNS settings |
GET | /flows | Network logs |
GET | /audit | Audit log |
GET | /audit/verify | Check the audit log's integrity |
GET | /hooks | Webhooks and log streams (read only with tokens) |
What tokens can't do
API tokens can't manage other tokens, workspaces, sign-ins or shared machines, can't write the audit log, and can't change webhooks or log streams. Use the dashboard for those.
Connect an AI agent (MCP)
The dashboard runs an MCP server, so an AI assistant can work with your workspace on your behalf. Open Connect your agent in the dashboard's sidebar for setup steps. Agents sign in with your account (OAuth), not with an API token.
Tools include:
- listing workspaces and machines
- getting an install command (with an auth key that works once, for 24 hours) and waiting for the machine to join
- approving machines, checking a connection, explaining how to connect to a machine
- renaming machines, inviting people and sharing machines
Approving machines, inviting people and sharing need an owner or admin.
To give an agent these docs, point it at docs.getunderpass.com/llms.txt.