Identity and sessions

API reference descriptions are provided in English to preserve the exact published contract.

Get organization authentication policy

GET /v1/accounts/{AC}/identity/auth-policy

getV1AccountsByAcIdentityAuthPolicy200

Required scope: any one of `roles:write`, `audit:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Replace organization authentication policy

PUT /v1/accounts/{AC}/identity/auth-policy

putV1AccountsByAcIdentityAuthPolicyIdempotency-Key required200

Required scope: `roles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (9 fields)

Request body
Name	Type	Required
`autoDisableInactiveApiKeys`	boolean	yes
`expectedVersion`	integer (1–)	yes
`mfaRequiredForAllRoles`	boolean	yes
`passwordLoginEnabled`	boolean	yes
`recoveryRevokesMfa`	boolean	yes
`sessionAbsoluteTimeoutHours`	integer (1–2160)	yes
`sessionIdleTimeoutMinutes`	integer (15–1440)	yes
`ssoEnforced`	boolean	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List the signed-in user's MFA credentials

GET /v1/accounts/{AC}/identity/mfa/credentials

getV1AccountsByAcIdentityMfaCredentialsPaginated200

Required scope: `api:access`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Revoke one MFA credential

DELETE /v1/accounts/{AC}/identity/mfa/credentials/{credentialId}

deleteV1AccountsByAcIdentityMfaCredentialsByCredentialid204

Required scope: `api:access`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`credentialId`	path · string (uuid)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Start WebAuthn or TOTP enrollment

POST /v1/accounts/{AC}/identity/mfa/enrollments

postV1AccountsByAcIdentityMfaEnrollmentsIdempotency-Key required201

Required scope: `api:access`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (3 fields)

Request body
Name	Type	Required
`displayName`	string (max 128 chars)
`method`	"WEBAUTHN" \| "TOTP"	yes
`providerKey`	string (pattern ^[a-z0-9][a-z0-9_-]*$, max 64 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Complete WebAuthn or TOTP enrollment

POST /v1/accounts/{AC}/identity/mfa/enrollments/{enrollmentId}/complete

postV1AccountsByAcIdentityMfaEnrollmentsByEnrollmentidCompleteIdempotency-Key required201

Required scope: `api:access`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`enrollmentId`	path · string (uuid)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`ceremonyRef`	string (max 1024 chars)	yes
`response`	string (max 32768 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Replace recovery codes and return the new codes once

POST /v1/accounts/{AC}/identity/mfa/recovery-codes/rotate

postV1AccountsByAcIdentityMfaRecoveryCodesRotateIdempotency-Key required201

Required scope: `api:access`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (1 fields)

Request body
Name	Type	Required	Description
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List the signed-in user's factors and start a WebAuthn step-up ceremony

POST /v1/accounts/{AC}/identity/mfa/verification-options

postV1AccountsByAcIdentityMfaVerificationOptionsIdempotency-Key required200

Required scope: `api:access`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (1 fields)

Request body
Name	Type	Required	Description
`action`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List organization identity providers

GET /v1/accounts/{AC}/identity/providers

getV1AccountsByAcIdentityProvidersPaginated200

Required scope: `api:access`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Stage an identity provider configuration

POST /v1/accounts/{AC}/identity/providers

postV1AccountsByAcIdentityProvidersIdempotency-Key required201

Required scope: `roles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (6 fields)

Request body
Name	Type	Required
`credentialRef`	string (max 512 chars)
`protocol`	"OIDC" \| "SAML" \| "SCIM" \| "WEBAUTHN" \| "TOTP"	yes
`providerKey`	string (pattern ^[a-z0-9][a-z0-9_-]*$, max 64 chars)	yes
`publicConfig`	object	yes
`reason`	string (max 2000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Verify and activate an identity provider

POST /v1/accounts/{AC}/identity/providers/{providerId}/activate

postV1AccountsByAcIdentityProvidersByProvideridActivateIdempotency-Key required200

Required scope: `roles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`providerId`	path · string (uuid)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 2000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Suspend an identity provider

POST /v1/accounts/{AC}/identity/providers/{providerId}/suspend

postV1AccountsByAcIdentityProvidersByProvideridSuspendIdempotency-Key required200

Deprovisioning: the provider stops backing sign-in, MFA or SCIM at once, every browser session it authenticated is revoked, and it can be re-verified and activated later. Required scope: `roles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`providerId`	path · string (uuid)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 2000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Exchange verified MFA or a one-use recovery code for a step-up token

POST /v1/accounts/{AC}/identity/step-up

postV1AccountsByAcIdentityStepUpIdempotency-Key requiredPaginated201

Required scope: `api:access`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Request body (5 fields)

Request body
Name	Type	Required	Description
`action`	string (max 256 chars)	yes	The action the grant is for, exactly as a STEP_UP_REQUIRED refusal names it in details[path=stepUpAction] (for example API_KEY_CREATE, API_KEY_ROTATE, WEBHOOK_ENDPOINT_CREATE, WEBHOOK_URL_CHANGE, WEBHOOK_SECRET_ROTATE, WEBHOOK_ENDPOINT_REENABLE). A grant for another name is not accepted. Step-up is for people signed in to the console; an API key with webhooks:write manages webhook endpoints without it.
`assertion`	string (max 32768 chars)	yes
`challenge`	string (max 256 chars)
`method`	"WEBAUTHN" \| "TOTP" \| "RECOVERY_CODE"	yes
`providerKey`	string (pattern ^[a-z0-9][a-z0-9_-]*$, max 64 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Reset all MFA factors for a user

POST /v1/accounts/{AC}/identity/users/{userSid}/mfa/reset

postV1AccountsByAcIdentityUsersByUsersidMfaResetIdempotency-Key required200

Required scope: `roles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`userSid`	path · string (US… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Revoke every active browser session for a user

POST /v1/accounts/{AC}/identity/users/{userSid}/sessions/revoke-all

postV1AccountsByAcIdentityUsersByUsersidSessionsRevokeAllIdempotency-Key required200

Required scope: `roles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`userSid`	path · string (US… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List active role bindings in the account scope

GET /v1/accounts/{AC}/role-bindings

getV1AccountsByAcRoleBindingsPaginated200

Required scope: any one of `roles:write`, `audit:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create an immutable role binding

POST /v1/accounts/{AC}/role-bindings

postV1AccountsByAcRoleBindingsIdempotency-Key required201

Required scope: `roles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (8 fields)

Request body
Name	Type	Required
`environment`	"live" \| "sandbox" \| "both"
`expiresAt`	string (date-time)
`inboxSid`	string (IB… SID)
`principalRef`	string (max 128 chars)	yes
`principalType`	"USER" \| "API_KEY"	yes
`role`	string (max 64 chars)	yes
`scopeKind`	"ORGANIZATION" \| "ACCOUNT" \| "SUBACCOUNT" \| "INBOX"	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Revoke an immutable role binding

DELETE /v1/accounts/{AC}/role-bindings/{bindingId}

deleteV1AccountsByAcRoleBindingsByBindingid204

Required scope: `roles:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`bindingId`	path · string (uuid)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 1000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List authoritative customer roles and permissions

GET /v1/accounts/{AC}/roles

getV1AccountsByAcRolesPaginated200

Required scope: any one of `roles:write`, `audit:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Discover the API key's account and region

GET /v1/me

getV1Me200

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.