Skip to main content
PUT
Set a tenant's authentication policy

Authorizations

Authorization
string
header
required

A machine-client token from POST /v1/auth/client-token. Reads need the pulse.read scope; provisioning and tenant updates need pulse.write, which the token only carries when requested_scopes asks for it. Creating, changing, disabling and resetting MFA for users, and the tenant sign-in policy, need a signed-in user's token instead: they reject API-key tokens.

Path Parameters

tenantId
string<uuid>
required

The tenant: a tenant_id from List tenants (GET /v1/msp/admin/tenants). Must be your own tenant or one beneath it.

Body

application/json

Replaces the whole policy: send every field, because an omitted require_sso is saved as false. Invalid values return 400 auth_request_invalid.

Tightening the policy (making MFA required, or removing an allowed method) signs every user of the tenant out: their existing tokens stop working.

mfa_requirement
enum<string>
required

Whether users must use multi-factor authentication: disabled | required.

  • required: every user must complete MFA, and users without a method are asked to set one up.
  • disabled: MFA is not forced, but users who have already set up a method are still asked for it.
Available options:
disabled,
required
allowed_mfa_methods
enum<string>[]
required

The MFA methods users may use: one or both of email and totp (an authenticator app). Must not be empty or repeat a value.

Available options:
email,
totp
expected_version
required

The version from your last read of the policy. If someone changed the policy since, the call returns 409 policy_version_conflict: read it again and retry.

require_sso
boolean
default:false

When true, users must sign in with the tenant's single sign-on. Defaults to false. Turning it on returns 409 require_sso_needs_sso_session unless you are signed in to this tenant with SSO yourself, so you cannot lock yourself out.

Response

OK

How users of one tenant sign in. The policy applies to that tenant only; tenants beneath it keep their own.

tenant_id
string<uuid>
required

The tenant the policy belongs to.

mfa_requirement
string
required

Whether users must use multi-factor authentication: disabled | required. New tenants start with disabled.

allowed_mfa_methods
enum<string>[]
required

The MFA methods users may use: email, totp (an authenticator app), or both. New tenants allow both.

Available options:
email,
totp
version
required

The policy's version. Send it as expected_version when you update the policy.

updated_at
string<date-time>
required

When the policy last changed: an ISO 8601 timestamp in UTC (offset +00:00).

require_sso
boolean
default:false

True when users must sign in with the tenant's single sign-on.