users_config_upsert

Tool

users_config_upsert

Create or update this product's end-user auth configuration.

Create or update this product's end-user auth configuration. Only the fields you pass change; the rest keep their current values. Rejected while the product is paused (archived or blocked by the platform). `email.templates` sends an auth email from a PUBLISHED template in this product's mail toolkit instead of the built-in one ({ "<purpose>": "<template id>" }, null unbinds). The template is not checked by this server: if mail cannot render it at send time, the built-in email is sent instead and the fallback is audited. Variables Users passes, per purpose (`*` = required: the template must use it; `?` = sent only sometimes, so the template must not require it; the rest are always sent): sign_in: code*, expires_in_minutes, link_url? verify: code*, expires_in_minutes, link_url? password_reset: link_url*, expires_in_minutes invite: link_url*, expires_in_minutes email_change_confirm: link_url*, expires_in_minutes email_change_approve: link_url*, expires_in_minutes, new_address email_change_revert: link_url*, expires_in_minutes, new_address email_change_override_cancel: link_url*, expires_in_minutes, new_address, takes_effect_in password_changed: none new_device: browser? email_change_completed: none email_change_reverted: none mfa_reset_scheduled: link_url*, expires_in_minutes, takes_effect_in mfa_reset: none impersonation: reason waitlist_confirm: link_url*, expires_in_minutes waitlist_joined: link_url*, expires_in_minutes

Behavior

HTTP: PUT /users/config

Arguments

Name	Type	Required	Description
mfa	object	—	MFA settings: backup-code batch size, the operator-reset delay, how fresh authentication must be to enroll, and the second-factor lockout ceilings. Merged field-by-field.
email	object	—	Email OTP / magic-link settings. Merged field-by-field. Set `email.from` to a sender on a domain verified in this product's mail toolkit — until then the email strategies are not offered.
oauth	object	—	OAuth provider credentials and switches, per provider. Merged field-by-field. A provider is offered as a sign-in strategy only when it is enabled AND a full client id + secret pair resolves — from here, or from the deployment's shared development credentials.
invite	object	—	Invite lifetime and re-invite cooldown. Merged field-by-field.
captcha	object	—	Captcha (Cloudflare Turnstile) settings for flow creation. Merged field-by-field.
passkeys	object	—	Passkey (WebAuthn) settings: whether this product is a relying party, the RP ID and name, and whether an assertion must be user-verified. Merged field-by-field. The `passkey` strategy is offered only when `enabled` is true AND an RP ID resolves.
recovery	object	—	Password-recovery settings (whether it is offered, how long a reset link lives). Merged field-by-field.
testMode	object	—	Test mode: whether this product may have TEST USERS — accounts that are excluded from metering, kept out of the default directory listing, never really emailed, and (when the deployment sets one) able to sign in with the fixed magic OTP. REFUSED on a production deployment. Merged field-by-field.
waitlist	object	—	Waitlist settings: the double-opt-in toggle, how long a pending entry is retained before the sweep erases it, the confirmation link lifetime, and the embeddable widget’s copy and colours. Merged field-by-field, including inside `widget`.
retention	object	—	How long DEAD rows are kept before the retention sweep removes them: spent one-time tokens, expired flow attempts, expired sessions and their refresh tokens. These are grace periods on top of expiry, never lifetimes — an unswept expired row is inert. Merged field-by-field.
protection	object	—	Rate limits, lockout and breached-password settings. Merged field-by-field.
signupMode	string	—	How end users may join this product: 'public' (anyone), 'invite-only', or 'waitlist'. Default 'public'.
emailChange	object	—	Email-change settings: confirmation lifetime, the old address's revert window, the post-revert cooldown and the operator-override delay. Merged field-by-field.
notifications	object	—	Which security notification emails this product sends. All on by default. Merged field-by-field.
allowedOrigins	array	—	Browser origins allowed to drive this product's end-user flows, up to 20. Scheme + host + port only, matched exactly. Replaces the whole list. Empty means "no browser origin" once this product has a publishable key.
passwordPolicy	object	—	Password rules for this product. Merged field-by-field into the current policy.
sessionTtlHours	integer	—	End-user session lifetime in hours. Default 720 (30 days).
refreshSlidingDays	integer	—	Inactivity window of a session in days — every refresh slides it forward. Default 30.
refreshAbsoluteDays	integer	—	Hard time-box of a session in days, counted from sign-in and never extended. Default 365.
redirectUriAllowlist	array	—	Callback URIs the browser code handoff may deliver a one-time authorization code to, up to 20. Matched EXACTLY — no wildcards, no prefixes, no fragments — so list every callback in full. Replaces the whole list.
accessTokenTtlMinutes	integer	—	Access JWT lifetime in minutes, 5-60. Default 10. Short on purpose: a revoked session dies within one TTL.

Response

Field	Type	Always
mfa	object	•
email	object	•
oauth	object	•
invite	object	•
status	string	•
captcha	object	•
passkeys	object	•
recovery	object	•
testMode	object	•
waitlist	object	•
productId	string	•
retention	object	•
protection	object	•
signupMode	string	•
emailChange	object	•
notifications	object	•
allowedOrigins	array	•
passwordPolicy	object	•
sessionTtlHours	integer	•
lifecycleBlocked	boolean	•
lifecycleArchived	boolean	•
refreshSlidingDays	integer	•
refreshAbsoluteDays	integer	•
redirectUriAllowlist	array	•
accessTokenTtlMinutes	integer	•
captchaSecretConfigured	boolean	•

Try it

Create or update this product's end-user auth configuration.

When to use

Example

Ask your agent something like this:

Create or update this product's end-user auth configuration.

The agent will invoke users_config_upsert with these arguments:

{}