API / Integration workflows

Connect machines and services.

These operations require matching server capabilities and configured backends. Authenticate account requests with a bearer token; enrolled device requests use the signed agent protocol.

Operation-only signing

Inspect GET /api/v1/crypto/backends with credentials:read. List account-owned handles using GET /api/v1/crypto/signing-keys?backend=pkcs11 with keys:sign.

POST /api/v1/crypto/sign
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "backend": "pkcs11",
  "key_id": "<ACCOUNT_OWNED_KEY_HANDLE>",
  "message": "aGVsbG8=",
  "purpose": "release-verification"
}

The message must be base64 representing 1 byte to 1 MiB. The result includes a base64 signature, algorithm, key ID, and audit ID in the standard success response. Private key material is not returned. Unknown account-owned keys return 404; signing device failures can return 502. See the MCP bridge guide for agent integration.

Device enrollment and grants

Administrators create profiles with PUT /api/v1/agents/profiles/:id. Grants name exact existing resources; wildcard grants are not accepted. Management routes require admin:*; device authorization review and approval use agents:approve.

PUT /api/v1/agents/profiles/<PROFILE_UUID>
{
  "name": "web-production",
  "enabled": true,
  "grants": [
    { "alias": "app-config", "service": "secret.read", "resource": "<SECRET_UUID>" },
    { "alias": "database", "service": "database.issue", "resource": "<ROLE_UUID>" }
  ]
}

The agent uses /api/v1/agent/oauth/device, /token, and /enroll for device authorization, or POST /api/v1/agents/devices for account-credential enrollment. After enrollment it signs requests to /api/v1/agent/identity and /api/v1/agent/access/:alias. Use the agent implementation for canonical signing and replay protection.

Revoke devices with DELETE /api/v1/agents/devices/:id. Revocation applies to subsequent requests; it cannot withdraw copied values or revoke existing database leases. Enrollment and service setup →

Database credentials and leases

Configure a supported database role and its account-owned role record before issuing credentials. These endpoints do not provision a database server.

Operation	Scope
`POST /api/v1/database/roles/:id/credentials`	database:issue
`POST /api/v1/database/roles/:id/rotate`	database:rotate
`DELETE /api/v1/database/leases/:id`	database:revoke

Protect returned credentials and retain the lease identifier for lifecycle management. Rotation and lease revocation have different effects; explicitly revoke outstanding dynamic leases when access must end.

Named variables

Bind a name to a credential UUID and field using PUT /api/v1/variables/:name. Resolve names or templates with POST /api/v1/variables/resolve. Assignment management requires variables:read or variables:write; resolution checks underlying resource access.

Request formats, SDK examples, and agent grants →

Certificates, federation, and credentials

The directory includes certificate enrollment and downloads, SSH and GPG keys, TOTP and YubiKey resources, JKS entries, SAML metadata and assertions, OIDC clients and JWKS, auditing, webhooks, and specialized credential collections. Each has its own fields and lifecycle. See the SDK guide for examples and compatibility requirements.

Operational boundaries

AutoHSM operates beside Vault using its own PKCS#11 configuration; it is not a SecretServer REST endpoint. SeKretSauce and aikeys can work locally without an account. The clients repository’s encrypted cache service is a design package, not an operational daemon.