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

Agent Lifecycle¶

Control-plane lifecycle operations for a registered agent. All require the agent:admin permission. Unregistering or revoking an agent invalidates its mTLS identity and recovery tokens and blocks all future runtime use; history is preserved. These operations do not delete a generated install-script record (see DELETE /api/v1/deployments/{id}).

Get Lifecycle Impact¶

GET /api/v1/agents/{id}/lifecycle-impact HTTP/1.1
Authorization: Bearer <jwt>

Returns an advisory dependency summary (managed certificates, project bindings, rotation targets, SSH keys, pending keytab deployments, discovery/config/token references) plus blockers and warnings. Counts are best-effort; gateway task payloads are not fully scanned.

Unregister Agent¶

POST /api/v1/agents/{id}/unregister HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json

{ "reason": "host decommissioned", "reason_category": "decommission", "force": false }

reason_category of compromised, lost_credential, or stolen_host escalates the retire into a security revoke. Without force, unresolved blockers (managed certificates, pending keytab deployments) return 409 Conflict. Response 200 OK returns the lifecycle result.

Re-register Agent (issue replacement token)¶

POST /api/v1/agents/{id}/reregister HTTP/1.1
Authorization: Bearer <jwt>

{ "reason": "mTLS certificate compromised" }

Retires the old identity (if still active) and returns a single-use replacement bootstrap token (valid 24 h) for re-enrolling the host.

Remote Uninstall Agent¶

POST /api/v1/agents/{id}/uninstall HTTP/1.1
Authorization: Bearer <jwt>

{ "reason": "host decommission" }

Asks a connected agent to uninstall itself. Requires a live connection and a supported platform (Linux systemd package installs, or Windows MSI service installs). Returns 202 Accepted when the agent accepts, 409 Conflict if the agent is not connected/active, or 422 Unprocessable Entity if the platform/layout is unsupported (fall back to unregister + manual removal).

202 Accepted means the request was accepted, not that the host was removed. A detached runner performs the uninstall and reports the terminal outcome over the health channel (POST /api/v1/agents/me/health with an uninstall block). On a reported success the agent is retired automatically; on failure the agent stays active with uninstall_status = failed so an operator can retry. If no report arrives, the agent is shown as awaiting confirmation.

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`
Lifecycle impact / unregister / reregister / uninstall	`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¶

Agent Lifecycle¶

Get Lifecycle Impact¶

Unregister Agent¶

Re-register Agent (issue replacement token)¶

Remote Uninstall Agent¶

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`¶