Change an Environment's sign-in settings
/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/{envSlug}/auth-settingsUpdates the sign-in settings of the Environment named by :envSlug, applying any supplied fields (mfa, allow_self_signup, self_signup_require_captcha, login_require_captcha, password_login_enabled, email_otp_login_enabled, self_signup_daily_cap, access_token_ttl_seconds, refresh_token_ttl_days, allowed_web_origins, sso_return_urls); omitted fields are left unchanged and allowed_web_origins are normalized and de-duplicated on save. Returns 404 when the slug does not exist. Emits an environment.auth_settings_updated audit event recording which keys changed.
Authentication
AuthorizationJWT access token. Never send alongside X-API-Key: a request carrying both is refused.
auth_settings.manageDeveloper ConsoleChange Environment sign-in settings. Granted through an administrator role in the Admin Workspace; a valid token without it is refused with 403.
Path Parameters
envSlugstring Required Request body
application/json
mfaobject Optional MFA enforcement keys persisted under `env.settings`. Send the subset of keys you want to change; omitted keys retain their prior value.
allow_self_signupboolean Optional Per-environment opt-in for browser-direct, publishable-key self-signup (`POST /v1/identity/auth/register`). Off by default; persisted under `env.settings.allow_self_signup`.
self_signup_require_captchaboolean Optional Require a Cloudflare Turnstile CAPTCHA on self-signup for this Environment. Off by default; persisted under `env.settings.self_signup_require_captcha`. Enable only once the signup page renders the Turnstile widget, or registrations will be rejected.
login_require_captchaboolean Optional Require a Cloudflare Turnstile CAPTCHA on login for this Environment. Off by default; persisted under `env.settings.login_require_captcha`. Enable only once the login page renders the Turnstile widget, or logins will be rejected.
password_login_enabledboolean Optional Enable password (email + password) login for this Environment. On by default; persisted under `env.settings.password_login_enabled`. Set false for a passwordless-only Environment.
email_otp_login_enabledboolean Optional Enable passwordless email-OTP login for this Environment. Off by default (opt-in); persisted under `env.settings.email_otp_login_enabled`. When on, identities can sign in with an emailed 6-digit code via /login/email-otp/*.
self_signup_daily_capnumber Optional Maximum self-signup registrations allowed per UTC day for this Environment. 0 (the default) means no cap. When exceeded, registration returns 429. Persisted under `env.settings.self_signup_daily_cap`.
access_token_ttl_secondsnumber Optional Lifetime in seconds of the access tokens (JWTs) this Environment issues to identities. Defaults to 900 (15 minutes). Persisted under `env.settings.access_token_ttl_seconds`; applies to tokens minted after the change.
refresh_token_ttl_daysnumber Optional Lifetime in days of the refresh tokens this Environment issues to identities — effectively how long a session survives without re-authentication. Defaults to 180. Persisted under `env.settings.refresh_token_ttl_days`; applies to tokens minted after the change.
allowed_web_originsstring[] Optional Browser Origins allowed to call this Environment's public identity-auth API cross-origin (CORS), e.g. `https://app.example.com`. Required to use the Direct-API flow from a browser SPA; empty means no browser client is permitted (server-to-server with an API key is unaffected). Persisted under `env.settings.allowed_web_origins`.
sso_return_urlsstring[] Optional Allowlist of return URLs for publishable-key (Direct-API) SSO. After the IdP round-trip, `/v1/identity/auth/sso/*` redirects back to one of these with a single-use `sso_token`; an unregistered return URL is rejected (exact match — no open redirect). Persisted under `env.settings.sso_return_urls`.
Responses
application/json
dataEnvironmentAuthSettingsResponseDto
application/json
errorApiErrorBodyDto
application/json
errorApiErrorBodyDto
application/json
errorApiErrorBodyDto
application/json
errorApiErrorBodyDto
Errors
When the request can't be completed, the response body includes a stable error code you can branch on.
account.capability_requiredForbiddenThe signed-in user's administrator roles do not grant the capability this endpoint requires.
Ask an account administrator to grant a role carrying the capability named in the Authentication section, then retry.
Returned object
curl -X PATCH "https://auth.canopy-io.com/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/value/auth-settings" \ -H "Authorization: Bearer $CANOPY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mfa": { "mfa_required": false, "mfa_grace_period_days": 0, "mfa_trusted_device_days": 0, "mfa_factor_allowlist": [ "totp" ], "mfa_after_sso": "exempt", "webauthn_rp_id": "acme.com", "webauthn_origins": [ "https://portal.acme.com" ] }, "allow_self_signup": false, "self_signup_require_captcha": false, "login_require_captcha": false, "password_login_enabled": false, "email_otp_login_enabled": false, "self_signup_daily_cap": 0, "access_token_ttl_seconds": 0, "refresh_token_ttl_days": 0, "allowed_web_origins": [ "string" ], "sso_return_urls": [ "string" ] }'
{ "data": { "environment_slug": "string", "mfa_required": false, "mfa_grace_period_days": 0, "mfa_trusted_device_days": 0, "mfa_factor_allowlist": [ "string" ], "mfa_after_sso": "exempt", "webauthn_rp_id": "string", "webauthn_origins": [ "string" ], "allow_self_signup": false, "self_signup_require_captcha": false, "login_require_captcha": false, "password_login_enabled": false, "email_otp_login_enabled": false, "self_signup_daily_cap": 0, "access_token_ttl_seconds": 0, "refresh_token_ttl_days": 0, "allowed_web_origins": [ "string" ], "sso_return_urls": [ "string" ] } }
Tell us how we can improve this guide.