Tokens API¶

Register, Monitor, Renew, and Deploy Externally-Issued API Tokens

Document Version: 1.0.0
Last Updated: 2026-10-22

Feature Availability

Token Management is available from MazeVault v1.0.60 as an Enterprise Function. All endpoints below are gated by the token_management license feature (PoC and Enterprise licenses). Without it the API returns 403 Forbidden. See Licensing and the Token Management Guide.

Endpoints Overview¶

Method	Endpoint	Permission	Description
POST	`/api/v1/tokens`	`token:write`	Register a managed token
GET	`/api/v1/tokens`	`token:read`	List managed tokens
GET	`/api/v1/tokens/:id`	`token:read`	Get token by ID (with deployment targets)
PUT	`/api/v1/tokens/:id`	`token:write`	Update token metadata
DELETE	`/api/v1/tokens/:id`	`token:delete`	Delete token and its deployment targets
GET	`/api/v1/tokens/:id/value`	`token:admin`	Reveal the stored token value
POST	`/api/v1/tokens/:id/renew`	`token:write`	Renew the token value and expiry
GET	`/api/v1/tokens/:id/targets`	`token:read`	List deployment targets
POST	`/api/v1/tokens/:id/targets`	`token:write`	Add a deployment target
DELETE	`/api/v1/tokens/:id/targets/:targetId`	`token:write`	Remove a deployment target
POST	`/api/v1/tokens/:id/targets/:targetId/sync`	`token:write`	Deploy the current value to a target now

Managed tokens are organization-scoped; the organization is taken from the authenticated session. A token that belongs to another organization is answered with 404 Not Found.

Create Token¶

Registers an externally-issued token. The value is encrypted (or offloaded in Orchestrator Mode) immediately and is never returned by list or detail endpoints.

POST /api/v1/tokens HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "name": "jira-automation-token",
  "description": "CI automation token for Jira Cloud",
  "provider": "jira",
  "value": "ATATT3xFfGF0...",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "expires_at": "2027-01-01T00:00:00Z",
  "lead_time_days": 30,
  "metadata": { "owner": "platform-team", "ticket": "OPS-1234" }
}

Request Fields¶

Field	Type	Required	Description
`name`	string	✅	Unique name within the organization/project scope
`description`	string	—	Purpose of the token
`provider`	string	—	Free-text label of the issuing system (`jira`, `signi`, …)
`value`	string	✅	Token secret; write-only
`project_id`	string (UUID)	—	Optional project binding; required for deployment to project agents and integrations
`expires_at`	string (ISO 8601)	✅	Expiration timestamp as issued by the source system
`lead_time_days`	integer	—	Days before expiry when the `token_expiry` incident opens (default `30`)
`metadata`	object	—	Free-form key/value pairs

Response `201 Created`¶

{
  "id": "00000000-0000-4000-8000-000000000001",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "jira-automation-token",
  "description": "CI automation token for Jira Cloud",
  "provider": "jira",
  "storage_mode": "local",
  "expires_at": "2027-01-01T00:00:00Z",
  "lead_time_days": 30,
  "status": "active",
  "is_expired": false,
  "days_until_expiry": 436,
  "metadata": { "owner": "platform-team", "ticket": "OPS-1234" },
  "created_by": "a1b2c3d4-0000-0000-0000-000000000001",
  "created_at": "2026-10-22T08:00:00Z",
  "updated_at": "2026-10-22T08:00:00Z"
}

Token Object Fields¶

Field	Description
`storage_mode`	`local` (AES-256-GCM in database) or `external` (offloaded in Orchestrator Mode)
`external_provider_type`	Present when `storage_mode` is `external`; identifies the offload provider
`status`	`active`, `expired`, or `revoked`
`is_expired`	`true` once `expires_at` has passed
`days_until_expiry`	Whole days remaining (negative when expired)
`last_renewed_at`, `renewal_notes`	Set by the renew operation
`deployment_targets`	Included in the detail response only

List Tokens¶

GET /api/v1/tokens?status=active&provider=jira&page=1&limit=50 HTTP/1.1
Authorization: ******

Query Parameters¶

Parameter	Type	Description
`project_id`	UUID	Filter by project
`provider`	string	Filter by provider label
`status`	string	`active`, `expired`, or `revoked`
`page`	integer	Page number (default `1`)
`limit`	integer	Page size, max `200`

Response `200 OK`¶

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "jira-automation-token",
      "provider": "jira",
      "storage_mode": "local",
      "expires_at": "2027-01-01T00:00:00Z",
      "lead_time_days": 30,
      "status": "active",
      "is_expired": false,
      "days_until_expiry": 436,
      "created_at": "2026-10-22T08:00:00Z",
      "updated_at": "2026-10-22T08:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

Get Token¶

GET /api/v1/tokens/00000000-0000-4000-8000-000000000001 HTTP/1.1
Authorization: ******

Response `200 OK`¶

Returns the token object including its deployment_targets array (see Deployment Target Object).

Update Token¶

Updates metadata only. The token value can be changed exclusively through Renew Token.

PUT /api/v1/tokens/00000000-0000-4000-8000-000000000001 HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "description": "CI automation token for Jira Cloud (shared with release pipeline)",
  "lead_time_days": 45,
  "status": "active"
}

Request Fields¶

Field	Type	Description
`name`	string	New name (must stay unique)
`description`	string	New description
`provider`	string	New provider label
`expires_at`	string (ISO 8601)	Corrected expiration timestamp
`lead_time_days`	integer	New alert lead time
`status`	string	`active` or `revoked`
`metadata`	object	Replaces the metadata map

All fields are optional; omitted fields are left unchanged.

Response `200 OK`¶

Returns the updated token object.

Delete Token¶

Deletes the token and all of its deployment targets. In Orchestrator Mode the offloaded external value is removed as well.

DELETE /api/v1/tokens/00000000-0000-4000-8000-000000000001 HTTP/1.1
Authorization: ******

Response `204 No Content`¶

Reveal Token Value¶

Returns the decrypted (or externally fetched) value. Requires token:admin and is recorded in the audit log as TOKEN_REVEAL.

GET /api/v1/tokens/00000000-0000-4000-8000-000000000001/value HTTP/1.1
Authorization: ******

Response `200 OK`¶

{
  "value": "ATATT3xFfGF0..."
}

Renew Token¶

Records a value obtained manually in the source system together with its new expiry. Resolves the open token_expiry incident, resets the status to active, and re-deploys every target with sync_on_renewal: true.

POST /api/v1/tokens/00000000-0000-4000-8000-000000000001/renew HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "value": "ATATT3xFfGF0-new...",
  "expires_at": "2028-01-01T00:00:00Z",
  "renewal_notes": "Regenerated in Jira by ops on OPS-1301"
}

Request Fields¶

Field	Type	Required	Description
`value`	string	✅	New token secret
`expires_at`	string (ISO 8601)	✅	New expiration timestamp
`renewal_notes`	string	—	Free-text note stored on the token

Response `200 OK`¶

Returns the updated token object with last_renewed_at and renewal_notes populated.

List Deployment Targets¶

GET /api/v1/tokens/00000000-0000-4000-8000-000000000001/targets HTTP/1.1
Authorization: ******

Response `200 OK`¶

[
  {
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "token_id": "00000000-0000-4000-8000-000000000001",
    "target_type": "agent_file",
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "target_path": "/etc/jira-sync/config.json",
    "file_format": "json",
    "secret_key": "jira.api_token",
    "post_install_cmd": "systemctl restart jira-sync",
    "backup": true,
    "sync_on_renewal": true,
    "deployment_status": "deployed",
    "last_sync_at": "2026-10-22T08:05:00Z",
    "last_sync_status": "success"
  }
]

Add Deployment Target¶

POST /api/v1/tokens/00000000-0000-4000-8000-000000000001/targets HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "target_type": "kubernetes_secret",
  "integration_id": "9b2c1a7e-1111-2222-3333-444455556666",
  "config": {
    "namespace": "integrations",
    "secret_name": "jira-credentials",
    "key_name": "api-token"
  },
  "sync_on_renewal": true
}

Request Fields¶

Field	Type	Required	Description
`target_type`	string	—	`agent_file` (default), `kubernetes_secret`, `azure_keyvault`, `aws_secrets_manager`
`integration_id`	string (UUID)	per type	Integration used for non-agent targets
`config`	object	per type	Type-specific configuration (see below)
`agent_id`	string (UUID)	`agent_file`	Agent that manages the target file
`target_path`	string	`agent_file`	Absolute path of the configuration file
`file_format`	string	—	`json`, `yaml`, or `env` (default `env`)
`secret_key`	string	`agent_file`	Key under which the value is written (dot-notation for nested JSON/YAML keys)
`post_install_cmd`	string	—	Command executed by the agent after a successful write; must match the agent command allowlist
`backup`	boolean	—	Keep a timestamped copy of the previous file
`sync_on_renewal`	boolean	—	Re-deploy automatically after each renewal

Required Configuration per Target Type¶

`target_type`	Required fields
`agent_file`	`agent_id`, `target_path`, `secret_key`
`kubernetes_secret`	`config.namespace`, `config.secret_name`, `config.key_name`
`azure_keyvault`	`integration_id`, `config.secret_name`
`aws_secrets_manager`	`integration_id`, `config.secret_id`, `config.region`

Response `201 Created`¶

Returns the created Deployment Target Object with deployment_status: pending.

Delete Deployment Target¶

DELETE /api/v1/tokens/00000000-0000-4000-8000-000000000001/targets/0f8fad5b-d9cb-469f-a165-70867728950e HTTP/1.1
Authorization: ******

Response `204 No Content`¶

Sync Deployment Target¶

Pushes the current token value to the target immediately. Use it after adding a target or to retry a failed deployment.

POST /api/v1/tokens/00000000-0000-4000-8000-000000000001/targets/0f8fad5b-d9cb-469f-a165-70867728950e/sync HTTP/1.1
Authorization: ******

Response `200 OK`¶

Returns the updated Deployment Target Object with deployment_status, last_sync_at, last_sync_status, and — on failure — error_message.

Deployment Target Object¶

Field	Description
`id`, `token_id`	Identifiers
`target_type`	`agent_file`, `kubernetes_secret`, `azure_keyvault`, `aws_secrets_manager`
`agent_id`, `integration_id`, `config`	Target addressing (type-dependent)
`target_path`, `file_format`, `secret_key`, `post_install_cmd`, `backup`	Agent file options
`sync_on_renewal`	Re-deploy after renewal
`deployment_status`	`pending`, `deployed`, or `failed`
`last_sync_at`, `last_sync_status`, `error_message`	Result of the most recent deployment

Error Responses¶

All endpoints use standard MazeVault error responses:

HTTP Status	Meaning
`400 Bad Request`	Invalid body, missing `name` / `value` / `expires_at`, unsupported `target_type`, or missing type-specific target configuration
`401 Unauthorized`	Missing or invalid bearer token
`403 Forbidden`	Insufficient permission, or the `token_management` license feature is not available
`404 Not Found`	Token or deployment target does not exist in the caller's organization
`409 Conflict`	A token with the same name already exists in the scope
`503 Service Unavailable`	Orchestrator Mode is active but no secret offload provider is configured

📖 Token Management Guide
📖 Terraform Provider — mazevault_token
📖 Notifications & Alerting
🔐 RBAC Roles & Permissions
📖 Audit Log

Tokens API¶

Endpoints Overview¶

Create Token¶

Request Fields¶

Response 201 Created¶

Token Object Fields¶

List Tokens¶

Query Parameters¶

Response 200 OK¶

Get Token¶

Response 200 OK¶

Update Token¶

Request Fields¶

Response 200 OK¶

Delete Token¶

Response 204 No Content¶

Reveal Token Value¶

Response 200 OK¶

Renew Token¶

Request Fields¶

Response 200 OK¶

List Deployment Targets¶

Response 200 OK¶

Add Deployment Target¶

Request Fields¶

Required Configuration per Target Type¶

Response 201 Created¶

Delete Deployment Target¶

Response 204 No Content¶

Sync Deployment Target¶

Response 200 OK¶

Deployment Target Object¶

Error Responses¶

Related¶

Response `201 Created`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `204 No Content`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `201 Created`¶

Response `204 No Content`¶

Response `200 OK`¶