Skip to content

Service Account API

The Zaita Service Account API provides programmatic access to Secrets Management operations — creating and deleting Lockers, managing Secrets, and controlling access grants. This API is intended for automation scripts, infrastructure-as-code tooling, and custom integrations that need to manage secrets without using the web portal.

For information about creating and managing Service Accounts, see Machine Accounts.

Authentication

All Service Account API requests are authenticated with a Bearer token. The token is the Service Account's Client Secret, prefixed with the Client ID:

Authorization: Bearer <client_id>:<client_secret>

Service Accounts authenticate using their registered credentials. For federated authentication options, see Machine Accounts — Authentication.

Scopes

Secrets Management operations require specific scopes on the Service Account. Scopes are configured when creating or updating a Service Account.

Scope Grants
lockers:read List and view Lockers
lockers:write Create, delete, and manage access for Lockers
secrets:read List Secrets within a Locker
secrets:write Create and delete Secrets within a Locker
workloads:read List and view Workloads
workloads:write Create, update, and delete Workloads

Assign only the scopes required for the integration's intended operations.

Locker Endpoints

List Lockers

Returns all Lockers in the tenant Vault.

GET /api/v1/service/lockers

Required scope: lockers:read

Response:

{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "production-api-keys",
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-06-01T09:00:00Z"
    }
  ]
}

Create a Locker

Creates a new Locker in the tenant Vault.

POST /api/v1/service/lockers

Required scope: lockers:write

Request body:

{
  "name": "production-api-keys"
}

Response:

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "production-api-keys",
    "created_at": "2026-06-17T10:00:00Z",
    "updated_at": "2026-06-17T10:00:00Z"
  }
}

Get a Locker

Returns a Locker and its access lists.

GET /api/v1/service/lockers/{lockerUuid}

Required scope: lockers:read

Response:

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "production-api-keys",
    "courier_access": [
      { "courier_uuid": "...", "courier_name": "prod-courier", "permission": "read" }
    ],
    "workload_access": [
      { "workload_uuid": "...", "workload_name": "api-service", "permission": "read" }
    ],
    "bridge_cache": [
      { "bridge_uuid": "...", "bridge_name": "on-prem-bridge" }
    ]
  }
}

Delete a Locker

Deletes a Locker and all its Secrets. This action is irreversible.

DELETE /api/v1/service/lockers/{lockerUuid}

Required scope: lockers:write

Response:

{
  "success": true
}

Secret Endpoints

List Secrets

Returns all Secrets in a Locker. Secret values are not included in this response.

GET /api/v1/service/lockers/{lockerUuid}/secrets

Required scope: secrets:read

Response:

{
  "success": true,
  "data": [
    {
      "uuid": "a1b2c3d4-...",
      "name": "DB_PASSWORD",
      "description": "Main production database password",
      "created_at": "2026-06-01T09:00:00Z"
    }
  ]
}

Create a Secret

Adds a new Secret to a Locker. The value is encrypted before being stored.

POST /api/v1/service/lockers/{lockerUuid}/secrets

Required scope: secrets:write

Request body:

{
  "name": "DB_PASSWORD",
  "description": "Main production database password",
  "value": "s3cr3t-password"
}

Response:

{
  "success": true,
  "data": {
    "uuid": "a1b2c3d4-...",
    "name": "DB_PASSWORD",
    "description": "Main production database password",
    "created_at": "2026-06-17T10:00:00Z"
  }
}

Note: The value field is transmitted over TLS and encrypted by the platform before storage. Secret values are never returned by the API after creation.

Delete a Secret

Removes a Secret from a Locker permanently.

DELETE /api/v1/service/lockers/{lockerUuid}/secrets/{secretUuid}

Required scope: secrets:write

Response:

{
  "success": true
}

Access Control Endpoints

Grant Courier Access

Grants a registered Courier access to a Locker.

POST /api/v1/service/lockers/{lockerUuid}/access/courier/{courierUuid}

Required scope: lockers:write

Response:

{
  "success": true
}

Revoke Courier Access

DELETE /api/v1/service/lockers/{lockerUuid}/access/courier/{courierUuid}

Required scope: lockers:write

Grant Workload Access

Grants a registered Workload access to a Locker.

POST /api/v1/service/lockers/{lockerUuid}/access/workload/{workloadUuid}

Required scope: lockers:write

Revoke Workload Access

DELETE /api/v1/service/lockers/{lockerUuid}/access/workload/{workloadUuid}

Required scope: lockers:write

Assign a Bridge Cache

Assigns a Locker to a Bridge for in-memory caching.

POST /api/v1/service/lockers/{lockerUuid}/access/bridge/{bridgeUuid}

Required scope: lockers:write

Remove a Bridge Cache Assignment

DELETE /api/v1/service/lockers/{lockerUuid}/access/bridge/{bridgeUuid}

Required scope: lockers:write

Workload Endpoints

List Workloads

GET /api/v1/service/workloads

Required scope: workloads:read

Response: Paginated list of Workloads with name, UUID, auth method, status, and last-seen timestamp.

Create a Workload

POST /api/v1/service/workloads

Required scope: workloads:write

Request body:

{
  "name": "api-service",
  "description": "Production API service",
  "auth_method": "client_secret",
  "auth_config": {}
}

For auth_config fields per authentication method, see Workloads — Authentication.

Get a Workload

GET /api/v1/service/workloads/{workloadUuid}

Required scope: workloads:read

Update a Workload

PUT /api/v1/service/workloads/{workloadUuid}

Required scope: workloads:write

Delete a Workload

DELETE /api/v1/service/workloads/{workloadUuid}

Required scope: workloads:write

Audit Events

All Service Account API operations are recorded in the audit log. Key events include:

Event Description
service_account.locker.list Service Account listed Lockers
service_account.locker.created Service Account created a Locker
service_account.locker.deleted Service Account deleted a Locker
service_account.secret.created Service Account created a Secret
service_account.secret.deleted Service Account deleted a Secret
service_account.locker.courier_access.granted Service Account granted Courier access
service_account.locker.courier_access.revoked Service Account revoked Courier access
service_account.locker.workload_access.granted Service Account granted Workload access
service_account.locker.workload_access.revoked Service Account revoked Workload access
service_account.locker.bridge_cache.assigned Service Account assigned Locker to Bridge
service_account.locker.bridge_cache.removed Service Account removed Locker from Bridge

Audit log entries include the Service Account name, the requesting IP address, and a timestamp.

Next Steps