Appearance
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
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 500 | authentication service unavailable | Internal 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)
| Field | Type | Required |
|---|---|---|
| deny_unenrolled | boolean | No |
| name | string | No |
| priority | integer | No |
| required | boolean | Yes |
| subject_id | string | No |
| subject_kind | string | Yes |
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
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 422 | priority must be between -2147483648 and 2147483647 | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject does not exist | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject_id is required | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject_kind must be one of default, team, group, role | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path 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
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| deny_unenrolled | boolean | No |
| name | string | No |
| priority | integer | No |
| required | boolean | No |
| subject_id | string | No |
| subject_kind | string | No |
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
| Status | Code | Detail |
|---|---|---|
| 400 | at least one MFA policy field is required | Invalid Request; Invalid Request |
| 400 | request body must be valid JSON | Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 422 | priority must be between -2147483648 and 2147483647 | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject does not exist | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject_id is required | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject_kind must be one of default, team, group, role | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 500 | authentication service unavailable | Internal 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
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 500 | authentication service unavailable | Internal 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)
| Field | Type | Required |
|---|---|---|
| breach_check | boolean | No |
| history_count | integer | No |
| min_length | integer | No |
| name | string | No |
| priority | integer | No |
| require_digit | boolean | No |
| require_letter | boolean | No |
| require_lower | boolean | No |
| require_symbol | boolean | No |
| require_upper | boolean | No |
| subject_id | string | Yes |
| subject_kind | string | Yes |
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
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 422 | history_count must be between 0 and 24 | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | min_length must be between 1 and 1024 | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | priority must be between -2147483648 and 2147483647 | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject does not exist | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject_id is required | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject_kind must be one of user, team, group, role | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path 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
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| breach_check | boolean | No |
| history_count | integer | No |
| min_length | integer | No |
| name | string | No |
| priority | integer | No |
| require_digit | boolean | No |
| require_letter | boolean | No |
| require_lower | boolean | No |
| require_symbol | boolean | No |
| require_upper | boolean | No |
| subject_id | string | No |
| subject_kind | string | No |
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
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 422 | history_count must be between 0 and 24 | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | min_length must be between 1 and 1024 | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | priority must be between -2147483648 and 2147483647 | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject does not exist | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject_id is required | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 422 | subject_kind must be one of user, team, group, role | Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity |
| 500 | authentication service unavailable | Internal Server Error |