Agents API¶

Agent Registration, Heartbeat, Discovery, and Management

Document Version: 1.1.0
Last Updated: 2026-04-04

Overview¶

MazeVault Agents are lightweight processes deployed on infrastructure nodes that provide:

Automatic secret injection into applications
Certificate discovery across managed infrastructure
Real-time secret and certificate synchronization
Secure proxy for local application access to secrets

Endpoints Overview¶

Method	Endpoint	Auth	Description
POST	`/api/v1/agents/register`	Bootstrap Token	Register a new agent
POST	`/api/v1/agents/bootstrap`	JWT + `agent:admin`	Generate bootstrap token
GET	`/api/v1/agents`	JWT + `agent:admin`	List agents
GET	`/api/v1/agents/:id/discovery`	JWT + `agent:admin`	Get agent discovery results
GET	`/api/v1/agents/update/latest`	Agent Cert	Check for agent updates
POST	`/api/v1/agents/me/refresh-token`	mTLS	Refresh agent token
POST	`/api/v1/agents/me/health`	JWT	Report agent health
GET	`/api/v1/agents/me/certificates`	JWT	Get assigned certificates
GET	`/api/v1/agents/me/connect`	JWT	Agent WebSocket connection
POST	`/api/v1/agents/me/discovery/certificates`	JWT	Report discovered certificates
POST	`/api/v1/agents/me/password-requests`	JWT	Create password request
GET	`/api/v1/agents/me/password-requests`	JWT	Get pending password responses
POST	`/api/v1/agents/me/ssh-discovery`	JWT	Report discovered SSH keys

Agent Registration¶

Step 1: Generate Bootstrap Token¶

Create a bootstrap token in the MazeVault web interface:

Settings → Agents → Generate Bootstrap Token

The token is valid for a configurable period (default: 24 hours) and can be used for a specified number of registrations.

Step 2: Register Agent¶

POST /api/v1/agents/register HTTP/1.1
Content-Type: application/json

{
  "token": "***REMOVED***",
  "name": "app-server-01",
  "hostname": "app-server-01.example.com",
  "os_type": "linux",
  "metadata": {
    "environment": "production",
    "datacenter": "eu-west-1",
    "role": "application-server"
  }
}

Request Fields¶

Field	Type	Required	Description
`token`	string	✅	Bootstrap token
`name`	string	✅	Agent display name
`hostname`	string	—	FQDN of the host
`os_type`	string	—	Operating system type (e.g., `linux`, `windows`)
`metadata`	object	—	Key-value metadata (replaces labels)

Response `201 Created`¶

{
  "id": "agt_xyz789",
  "token": "eyJ...",
  "mtls_template_id": "tmpl_agent_mtls"
}

Field	Description
`id`	Agent ID for subsequent requests
`token`	JWT token for authenticated API calls
`mtls_template_id`	Certificate template ID for mTLS enrollment

Agent Health¶

Agents periodically report their health status:

POST /api/v1/agents/me/health HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "healthy",
  "uptime_seconds": 86400,
  "metrics": {
    "cpu_percent": 15.2,
    "memory_percent": 42.8,
    "disk_percent": 67.1
  },
  "managed_secrets": 12,
  "managed_certificates": 5,
  "last_sync": "2026-02-10T16:55:00Z"
}

Response `200 OK`¶

{
  "acknowledged": true,
  "server_time": "2026-02-10T17:00:00Z",
  "commands": []
}

The commands array may contain pending instructions for the agent (e.g., force sync, certificate renewal).

Certificate Discovery¶

Agents can scan their local infrastructure and report discovered certificates:

POST /api/v1/agents/me/discovery/certificates HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "certificates": [
    {
      "subject": "CN=legacy-app.internal,O=Example Corp",
      "serial_number": "AB:CD:EF:01:23",
      "issuer": "CN=Internal CA",
      "not_before": "2025-06-15T00:00:00Z",
      "not_after": "2026-06-15T00:00:00Z",
      "location": "/etc/ssl/certs/legacy-app.pem",
      "fingerprint": "SHA256:abc123...",
      "dns_names": ["legacy-app.internal"],
      "ip_addresses": ["10.0.2.50"],
      "source": "filesystem",
      "is_managed": false
    }
  ]
}

Response `200 OK`¶

{
  "accepted": 1,
  "duplicates": 0,
  "errors": 0
}

Discovered certificates appear in the MazeVault web interface under Certificates → Discovered for review and optional import.

List Agents¶

GET /api/v1/agents?status=online&page=1 HTTP/1.1
Authorization: Bearer <token>

Admin Only

This endpoint requires the agent:admin permission.

Query Parameters¶

Parameter	Type	Description
`status`	string	Filter: `online`, `offline`, `degraded`
`label`	string	Filter by label (key=value)
`search`	string	Search by hostname
`page`	integer	Page number
`per_page`	integer	Items per page

Response `200 OK`¶

{
  "data": [
    {
      "id": "agt_xyz789",
      "hostname": "app-server-01.example.com",
      "status": "online",
      "platform": "linux/amd64",
      "agent_version": "1.8.0",
      "labels": {
        "environment": "production",
        "datacenter": "eu-west-1"
      },
      "last_heartbeat": "2026-02-10T17:00:00Z",
      "managed_secrets": 12,
      "managed_certificates": 5,
      "registered_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Agent Status¶

Status	Description	Condition
`online`	Agent healthy and reporting	Last heartbeat < 2× interval
`degraded`	Agent reporting issues	Heartbeat received but metrics show problems
`offline`	Agent not responding	Last heartbeat > 3× interval

Required Permissions¶

Operation	Required Permission
Register Agent	Bootstrap token (no user auth)
List Agents	`agent:admin`
Generate Bootstrap Token	`agent:admin`
Get Discovery Results	`agent:admin`
Agent health / discovery / password-requests	Agent JWT (self-service)
Refresh Token	mTLS client certificate

Agent Password Requests¶

Agents can request password rotations on behalf of managed services:

Create Password Request¶

POST /api/v1/agents/me/password-requests HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Get Pending Responses¶

GET /api/v1/agents/me/password-requests HTTP/1.1
Authorization: Bearer <token>

Admin Password Request Management¶

Method	Endpoint	Permission	Description
GET	`/api/v1/admin/password-requests`	`agent:admin`	List all password requests
POST	`/api/v1/admin/password-requests/:id/approve`	`agent:admin`	Approve request
POST	`/api/v1/admin/password-requests/:id/reject`	`agent:admin`	Reject request

SSH Key Discovery¶

Agents can report discovered SSH keys from managed hosts:

POST /api/v1/agents/me/ssh-discovery HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

SSH key management is available under /api/v1/ssh/discovery (requires ssh:discover permission).

Agent Update Check¶

GET /api/v1/agents/update/latest HTTP/1.1

Returns the latest available agent version for auto-update.

Getting Started — API authentication
Secrets API — Secret management
Quick Start Guide — Initial setup

Agents API¶

Overview¶

Endpoints Overview¶

Agent Registration¶

Step 1: Generate Bootstrap Token¶

Step 2: Register Agent¶

Request Fields¶

Response 201 Created¶

Agent Health¶

Response 200 OK¶

Certificate Discovery¶

Response 200 OK¶

List Agents¶

Query Parameters¶

Response 200 OK¶

Agent Status¶

Required Permissions¶

Agent Password Requests¶

Create Password Request¶

Get Pending Responses¶

Admin Password Request Management¶

SSH Key Discovery¶

Agent Update Check¶

Related¶

Response `201 Created`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶