Build

Management API

Manage policies, tools, agents and users as code, and pull the signed audit trail — from CI/CD, Terraform-style config, and SIEM collectors. Authenticated with a machine token, separate from the per-agent SDK key.

Machine token vs agent key

The Management API uses a machine token (plm_live_…) sent as Authorization: Bearer — distinct from the per-agent X-Pliuz-Api-Key the SDKs use to request approvals.

Least privilege by construction

A machine token carries fine-grained scopes and can never run approvals (the critical path is agent-key only) nor mint agent keys. A compromised agent can't rewrite its own policies, and a SIEM collector token can't approve anything.

Create a token

Mint, list and revoke tokens from the admin console at /integrations → API Tokens (admin role required). Pick the scopes and an expiry (90 days suggested). The plm_live_… plaintext is shown once — store it in a secret manager; Pliuz keeps only an HMAC-SHA256 hash and cannot recover it.

Token lifecycle is console-only

Minting and revoking tokens is NOT part of this API — a token can never mint or revoke another token. That stays on the authenticated admin session.

Scopes

A token holds a non-empty subset of a closed enum of 10 scopes (no *, no admin). A valid token missing a scope gets 403 insufficient_scope; a missing/expired/revoked token gets 401.

scopes

tools:read      tools:write       # read / register·update tools
policies:read   policies:write    # read / create·update·disable policies
agents:read     agents:write      # read / register agents
users:read      users:write       # read / create·archive users
events:read                       # audit trail, verify chain, anchors
events:export                     # download the signed JSONL export

Quickstart

curl

# A machine token authenticates with Authorization: Bearer (NOT X-Pliuz-Api-Key).
curl -H "Authorization: Bearer plm_live_…" https://pliuz.com/api/v1/policies

# Config-as-code: register a policy from your CI pipeline.
curl -X POST https://pliuz.com/api/v1/policies \
  -H "Authorization: Bearer plm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"refunds-over-1000","priority":10,
       "conditions":{">":[{"var":"amount_cents"},100000]},
       "approver_group":"finance","sla_seconds":3600,"enabled":true}'

python · pliuz

from pliuz import ManagementClient

mgmt = ManagementClient()  # reads PLIUZ_MANAGEMENT_KEY

mgmt.create_policy({
    "name": "refunds-over-1000", "priority": 10,
    "conditions": {">": [{"var": "amount_cents"}, 100000]},
    "approver_group": "finance", "sla_seconds": 3600, "enabled": True,
})

# Pull a signed audit chunk for your SIEM, and verify the chain.
export = mgmt.export_events(limit=1000)
assert mgmt.verify_chain()["verified"]

typescript · @pliuz/sdk

import { ManagementClient } from '@pliuz/sdk'

const mgmt = new ManagementClient() // reads PLIUZ_MANAGEMENT_KEY

await mgmt.createPolicy({
  name: 'refunds-over-1000', priority: 10,
  conditions: { '>': [{ var: 'amount_cents' }, 100000] },
  approver_group: 'finance', sla_seconds: 3600, enabled: true,
})

const verify = await mgmt.verifyChain()  // { verified: true }

Both SDKs ship a ManagementClient that reads PLIUZ_MANAGEMENT_KEY, exposes typed methods for every opened resource, and a generic request() escape hatch. The full contract lives in the hand-authored OpenAPI doc: api-spec/management-openapi.yaml.

Attribution

Every write via a machine token is attributed in the tamper-evident audit trail: the event payload carries acted_via = { type: "management_key", key_id, key_prefix, key_name }, covered by the hash chain. The plaintext and hash are never logged.