YOUHODLERBusiness API
Get access
View as Markdown

postProvision service account with roles

Required capabilityservice_accounts.createrole_assignments.create

Creates a service account and grants it the supplied roles in a single call. Equivalent to POST /service-accounts followed by N × POST /role-assignments, but saves the client the round-trips. Best-effort grant phase: the service account is always created if identity-service accepts it; per-role grant failures are reported in role_assignment_errors (preserving the input order) and the response is still 201. The plaintext client_secret is returned exactly once — store it before retrying any failed grants.

Request

Request URL

POST
POST /service-accounts/provision

Request Body

application/json
{
  "description": "Withdrawal automation account",
  "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "roles": [
    {
      "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  ]
}

Responses

Response

application/json
{
  "client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "client_secret": "cs_live_abc123placeholder",
  "client_secret_expires_at": "2026-05-01T10:00:00Z",
  "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "role_assignment_errors": [],
  "role_assignments": [],
  "service_account": {
    "description": "Withdrawal automation account",
    "created_at": "2026-05-01T10:00:00Z",
    "current_secret_expires_at": "2026-05-01T10:00:00Z",
    "etag": "W/\"sa-etag-0001\"",
    "external_id": "sa-ext-001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "previous_secret_expires_at": null,
    "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "service_account",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
}

Resource created successfully.