Skip to content

Policies API Reference ​

GET /policies/mfa ​

List MFA policies

Lists policies that require or allow MFA for users, teams, groups, roles, or all users, ordered by policy ID. Changes are audited and apply at the next login without revoking existing sessions. See REST pagination for the shared collection contract.

Required permission — iam:policies:any

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "created_at": "2026-01-01T00:00:00Z",
      "id": "01J8Z3MFAPOLICY0000000000001",
      "name": "team MFA",
      "priority": 100,
      "required": true,
      "subject_id": "01J8Z3TEAM000000000000001",
      "subject_kind": "team",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "next_cursor": ""
}

Errors ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
500authentication service unavailableInternal Server Error

POST /policies/mfa ​

Create an MFA policy

Use to create an MFA requirement for an existing team, group, role, or the default population. The highest-priority matching policy applies at password or passkey login; policy mutations are audited.

Required permission — iam:policies:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Request body (application/json) ​

FieldTypeRequired
deny_unenrolledbooleanNo
namestringNo
priorityintegerNo
requiredbooleanYes
subject_idstringNo
subject_kindstringYes
json
{
  "name": "team MFA",
  "priority": 100,
  "required": true,
  "subject_id": "01J8Z3TEAM000000000000001",
  "subject_kind": "team"
}

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "01J8Z3MFAPOLICY0000000000001",
  "name": "team MFA",
  "priority": 100,
  "required": true,
  "subject_id": "01J8Z3TEAM000000000000001",
  "subject_kind": "team",
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
422priority must be between -2147483648 and 2147483647Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject does not existUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject_id is requiredUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject_kind must be one of default, team, group, roleUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
500authentication service unavailableInternal Server Error

DELETE /policies/mfa/{id} ​

Delete an MFA policy

Use to remove an MFA policy. The deletion is audited and returns no body.

Required permission — iam:policies:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

GET /policies/mfa/{id} ​

Get an MFA policy

Use to retrieve one MFA policy before editing or removing it.

Required permission — iam:policies:any

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "01J8Z3MFAPOLICY0000000000001",
  "name": "team MFA",
  "priority": 100,
  "required": true,
  "subject_id": "01J8Z3TEAM000000000000001",
  "subject_kind": "team",
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

PATCH /policies/mfa/{id} ​

Update an MFA policy

Use to partially update an MFA policy. Omitted fields remain unchanged; subject changes must refer to an existing team, group, or role.

Required permission — iam:policies:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Path parameters ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
deny_unenrolledbooleanNo
namestringNo
priorityintegerNo
requiredbooleanNo
subject_idstringNo
subject_kindstringNo
json
{
  "priority": 200,
  "required": false
}

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "01J8Z3MFAPOLICY0000000000001",
  "name": "team MFA",
  "priority": 200,
  "required": false,
  "subject_id": "01J8Z3TEAM000000000000001",
  "subject_kind": "team",
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors ​

StatusCodeDetail
400at least one MFA policy field is requiredInvalid Request; Invalid Request
400request body must be valid JSONInvalid Request; Invalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
422priority must be between -2147483648 and 2147483647Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject does not existUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject_id is requiredUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject_kind must be one of default, team, group, roleUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
500authentication service unavailableInternal Server Error

GET /policies/password ​

List password policies

Lists password policies targeting users, teams, groups, or roles, ordered by policy ID. See REST pagination for the shared collection contract.

Required permission — iam:policies:any

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "breach_check": true,
      "history_count": 5,
      "id": "01J8Z3POLICY00000000000001",
      "min_length": 12,
      "name": "team baseline",
      "priority": 100,
      "subject_id": "01J8Z3TEAM000000000000001",
      "subject_kind": "team"
    }
  ],
  "next_cursor": ""
}

Errors ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
500authentication service unavailableInternal Server Error

POST /policies/password ​

Create a password policy

Use to create a password policy for an existing user, team, group, or role. When policies overlap, higher priority wins independently for each field; an unset field falls through to lower-priority policies and then to the built-in default.

Required permission — iam:policies:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Request body (application/json) ​

FieldTypeRequired
breach_checkbooleanNo
history_countintegerNo
min_lengthintegerNo
namestringNo
priorityintegerNo
require_digitbooleanNo
require_letterbooleanNo
require_lowerbooleanNo
require_symbolbooleanNo
require_upperbooleanNo
subject_idstringYes
subject_kindstringYes
json
{
  "breach_check": true,
  "history_count": 5,
  "min_length": 12,
  "name": "team baseline",
  "priority": 100,
  "require_digit": true,
  "require_letter": true,
  "subject_id": "01J8Z3TEAM000000000000001",
  "subject_kind": "team"
}

Responses ​

  • 200 — Successful response
json
{
  "breach_check": true,
  "created_at": "2026-01-01T00:00:00Z",
  "history_count": 5,
  "id": "01J8Z3POLICY00000000000001",
  "min_length": 12,
  "name": "team baseline",
  "priority": 100,
  "subject_id": "01J8Z3TEAM000000000000001",
  "subject_kind": "team",
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
422history_count must be between 0 and 24Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422min_length must be between 1 and 1024Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422priority must be between -2147483648 and 2147483647Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject does not existUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject_id is requiredUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject_kind must be one of user, team, group, roleUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
500authentication service unavailableInternal Server Error

DELETE /policies/password/{id} ​

Delete a password policy

Use to remove a password policy. The deletion is audited and returns no body.

Required permission — iam:policies:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

GET /policies/password/{id} ​

Get a password policy

Use to retrieve one password policy by ID before editing or removing it.

Required permission — iam:policies:any

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "breach_check": true,
  "created_at": "2026-01-01T00:00:00Z",
  "history_count": 5,
  "id": "01J8Z3POLICY00000000000001",
  "min_length": 12,
  "name": "team baseline",
  "priority": 100,
  "subject_id": "01J8Z3TEAM000000000000001",
  "subject_kind": "team",
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

PATCH /policies/password/{id} ​

Update a password policy

Use to partially update a password policy. Omitted fields remain unchanged; send null for nullable policy fields to clear them. When policies overlap, higher priority wins independently for each field; an unset field falls through to lower-priority policies and then to the built-in default.

Required permission — iam:policies:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Path parameters ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
breach_checkbooleanNo
history_countintegerNo
min_lengthintegerNo
namestringNo
priorityintegerNo
require_digitbooleanNo
require_letterbooleanNo
require_lowerbooleanNo
require_symbolbooleanNo
require_upperbooleanNo
subject_idstringNo
subject_kindstringNo
json
{
  "breach_check": false,
  "history_count": 8,
  "min_length": 14,
  "name": "strong team baseline"
}

Responses ​

  • 200 — Successful response
json
{
  "breach_check": false,
  "created_at": "2026-01-01T00:00:00Z",
  "history_count": 8,
  "id": "01J8Z3POLICY00000000000001",
  "min_length": 14,
  "name": "strong team baseline",
  "priority": 100,
  "subject_id": "01J8Z3TEAM000000000000001",
  "subject_kind": "team",
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
422history_count must be between 0 and 24Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422min_length must be between 1 and 1024Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422priority must be between -2147483648 and 2147483647Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject does not existUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject_id is requiredUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
422subject_kind must be one of user, team, group, roleUnprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
500authentication service unavailableInternal Server Error