API Reference
All endpoints require authentication (session cookie). State-changing endpoints also require the X-CSRF-Token header.
Authentication
After a successful login, the server issues a JWT token via an httpOnly cookie. Subsequent requests carry the cookie automatically — no need to set an Authorization header manually.
Setup
Used during first-time deployment. Automatically disabled after the admin account is created.
| Method |
Path |
Description |
GET |
/api/setup/status |
Check if setup is complete |
POST |
/api/setup/init |
Create admin account |
POST /api/setup/init
Request body:
{
"username": "admin",
"password": "your-strong-password"
}
Auth
| Method |
Path |
Description |
POST |
/api/auth/login |
Login |
GET |
/api/auth/me |
Get current user info |
POST |
/api/auth/logout |
Logout |
POST /api/auth/login
Request body:
{
"username": "admin",
"password": "your-password"
}
Users
| Method |
Path |
Description |
GET |
/api/users |
List all users |
POST |
/api/users |
Create a user |
DELETE |
/api/users/:username |
Delete a user |
PUT |
/api/users/:username/password |
Change user password |
POST /api/users
Request body:
{
"username": "newuser",
"password": "user-password"
}
PUT /api/users/:username/password
Request body:
{
"password": "new-password"
}
User Preferences
| Method |
Path |
Description |
PUT |
/api/preferences |
Update user preferences |
PUT /api/preferences
Request body:
{
"uiTheme": "dark",
"terminalTheme": "ghostty"
}
Agent Tokens
Used to authorize local machine agents to connect to the relay server.
| Method |
Path |
Description |
GET |
/api/tokens |
List all tokens |
POST |
/api/tokens |
Create a token |
PUT |
/api/tokens/:id/enabled |
Enable/disable a token |
DELETE |
/api/tokens/:token |
Delete a token |
POST /api/tokens
Request body:
{
"label": "Home Mac",
"notes": "Living room Mac Mini"
}
PUT /api/tokens/:id/enabled
Request body:
Agents
| Method |
Path |
Description |
GET |
/api/agents |
List connected agents |
DELETE |
/api/agents/:id |
Delete an agent |
DELETE |
/api/agents/:id/fingerprint |
Reset machine fingerprint |
When to Reset Fingerprint
When the agent's host machine has a hardware change or OS reinstall, the machine fingerprint changes, causing connection rejection. Use this endpoint to reset the fingerprint and allow the agent to re-bind.
Server Key
| Method |
Path |
Description |
GET |
/api/server-key |
Get server Ed25519 public key |
Audit Log
| Method |
Path |
Description |
GET |
/api/audit?limit=100 |
Get audit log entries |
Query parameters:
| Parameter |
Type |
Default |
Description |
limit |
number |
100 |
Maximum number of log entries to return |