stytchauth · bgier-stytch · Aug 6, 2025
@@ -48,8 +48,8 @@ public interface Organizations {
     /**
      * Creates an Organization. An `organization_name` and a unique `organization_slug` are required.
      *
-     * By default, `email_invites` and `sso_jit_provisioning` will be set to `ALL_ALLOWED`, and `mfa_policy` will be set to
-     * `OPTIONAL` if no Organization authentication settings are explicitly defined in the request.
+     * If no Organization authentication setting parameters are passed in, `email_invites` will default to `ALL_ALLOWED` so
+     * that the Organization has a way to add Members. Otherwise, `email_invites` will default to `NOT_ALLOWED`.
      *
      * *See the [Organization authentication settings](https://stytch.com/docs/b2b/api/org-auth-settings) resource to learn
      * more about fields like `email_jit_provisioning`, `email_invites`, `sso_jit_provisioning`, etc., and their behaviors.
@@ -59,8 +59,8 @@ public interface Organizations {
     /**
      * Creates an Organization. An `organization_name` and a unique `organization_slug` are required.
      *
-     * By default, `email_invites` and `sso_jit_provisioning` will be set to `ALL_ALLOWED`, and `mfa_policy` will be set to
-     * `OPTIONAL` if no Organization authentication settings are explicitly defined in the request.
+     * If no Organization authentication setting parameters are passed in, `email_invites` will default to `ALL_ALLOWED` so
+     * that the Organization has a way to add Members. Otherwise, `email_invites` will default to `NOT_ALLOWED`.
      *
      * *See the [Organization authentication settings](https://stytch.com/docs/b2b/api/org-auth-settings) resource to learn
      * more about fields like `email_jit_provisioning`, `email_invites`, `sso_jit_provisioning`, etc., and their behaviors.
@@ -73,8 +73,8 @@ public interface Organizations {
     /**
      * Creates an Organization. An `organization_name` and a unique `organization_slug` are required.
      *
-     * By default, `email_invites` and `sso_jit_provisioning` will be set to `ALL_ALLOWED`, and `mfa_policy` will be set to
-     * `OPTIONAL` if no Organization authentication settings are explicitly defined in the request.
+     * If no Organization authentication setting parameters are passed in, `email_invites` will default to `ALL_ALLOWED` so
+     * that the Organization has a way to add Members. Otherwise, `email_invites` will default to `NOT_ALLOWED`.
      *
      * *See the [Organization authentication settings](https://stytch.com/docs/b2b/api/org-auth-settings) resource to learn
      * more about fields like `email_jit_provisioning`, `email_invites`, `sso_jit_provisioning`, etc., and their behaviors.

@@ -433,6 +433,10 @@ public interface Members {
      * The member will receive an Email Magic Link that expires in 5 minutes. If they do not verify their new email address in
      * that timeframe, the email
      * will be freed up for other members to use.
+     *
+     * The Magic Link will redirect to your `login_redirect_url` (or the configured default if one isn't provided), and you
+     * should invoke the [Authenticate Magic Link](https://stytch.com/docs/b2b/api/authenticate-magic-link) endpoint as normal
+     * to complete the flow.
      */
     public suspend fun startEmailUpdate(
         data: StartEmailUpdateRequest,
@@ -452,6 +456,10 @@ public interface Members {
      * The member will receive an Email Magic Link that expires in 5 minutes. If they do not verify their new email address in
      * that timeframe, the email
      * will be freed up for other members to use.
+     *
+     * The Magic Link will redirect to your `login_redirect_url` (or the configured default if one isn't provided), and you
+     * should invoke the [Authenticate Magic Link](https://stytch.com/docs/b2b/api/authenticate-magic-link) endpoint as normal
+     * to complete the flow.
      */
     public fun startEmailUpdate(
         data: StartEmailUpdateRequest,
@@ -472,6 +480,10 @@ public interface Members {
      * The member will receive an Email Magic Link that expires in 5 minutes. If they do not verify their new email address in
      * that timeframe, the email
      * will be freed up for other members to use.
+     *
+     * The Magic Link will redirect to your `login_redirect_url` (or the configured default if one isn't provided), and you
+     * should invoke the [Authenticate Magic Link](https://stytch.com/docs/b2b/api/authenticate-magic-link) endpoint as normal
+     * to complete the flow.
      */
     public fun startEmailUpdateCompletable(
         data: StartEmailUpdateRequest,

@@ -43,8 +43,11 @@ public interface Sms {
      * their phone number. In that case, this endpoint should only be used for subsequent authentication events, such as
      * prompting a Member for an OTP again after a period of inactivity.
      *
-     * Passing an intermediate session token, session token, or session JWT is not required, but if passed must match the
-     * Member ID passed.
+     * If the Member already has an active MFA factor, then passing an intermediate session token, session token, or session
+     * JWT with the existing MFA factor on it is required to prevent bypassing MFA.
+     *
+     * Otherwise, passing an intermediate session token, session token, or session JWT is not required, but if passed must
+     * match the `member_id` passed.
      *
      * ### Cost to send SMS OTP
      * Before configuring SMS or WhatsApp OTPs, please review how Stytch
@@ -56,8 +59,9 @@ public interface Sms {
      *
      * __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS
      * prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's
-     * allowlist via [the API](https://stytch.com/docs/workspace-management/pwa/country-code-allowlist-object), and
-     * [add credit card details](https://stytch.com/docs/dashboard/settings/billing) to your account.
+     * allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or
+     * [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and
+     * [add credit card details](https://stytch.com/dashboard/settings/billing) to your account.
      */
     public suspend fun send(data: SendRequest): StytchResult<SendResponse>
 
@@ -81,8 +85,11 @@ public interface Sms {
      * their phone number. In that case, this endpoint should only be used for subsequent authentication events, such as
      * prompting a Member for an OTP again after a period of inactivity.
      *
-     * Passing an intermediate session token, session token, or session JWT is not required, but if passed must match the
-     * Member ID passed.
+     * If the Member already has an active MFA factor, then passing an intermediate session token, session token, or session
+     * JWT with the existing MFA factor on it is required to prevent bypassing MFA.
+     *
+     * Otherwise, passing an intermediate session token, session token, or session JWT is not required, but if passed must
+     * match the `member_id` passed.
      *
      * ### Cost to send SMS OTP
      * Before configuring SMS or WhatsApp OTPs, please review how Stytch
@@ -94,8 +101,9 @@ public interface Sms {
      *
      * __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS
      * prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's
-     * allowlist via [the API](https://stytch.com/docs/workspace-management/pwa/country-code-allowlist-object), and
-     * [add credit card details](https://stytch.com/docs/dashboard/settings/billing) to your account.
+     * allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or
+     * [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and
+     * [add credit card details](https://stytch.com/dashboard/settings/billing) to your account.
      */
     public fun send(
         data: SendRequest,
@@ -122,8 +130,11 @@ public interface Sms {
      * their phone number. In that case, this endpoint should only be used for subsequent authentication events, such as
      * prompting a Member for an OTP again after a period of inactivity.
      *
-     * Passing an intermediate session token, session token, or session JWT is not required, but if passed must match the
-     * Member ID passed.
+     * If the Member already has an active MFA factor, then passing an intermediate session token, session token, or session
+     * JWT with the existing MFA factor on it is required to prevent bypassing MFA.
+     *
+     * Otherwise, passing an intermediate session token, session token, or session JWT is not required, but if passed must
+     * match the `member_id` passed.
      *
      * ### Cost to send SMS OTP
      * Before configuring SMS or WhatsApp OTPs, please review how Stytch
@@ -135,8 +146,9 @@ public interface Sms {
      *
      * __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS
      * prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's
-     * allowlist via [the API](https://stytch.com/docs/workspace-management/pwa/country-code-allowlist-object), and
-     * [add credit card details](https://stytch.com/docs/dashboard/settings/billing) to your account.
+     * allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or
+     * [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and
+     * [add credit card details](https://stytch.com/dashboard/settings/billing) to your account.
      */
     public fun sendCompletable(data: SendRequest): CompletableFuture<StytchResult<SendResponse>>
 

@@ -31,7 +31,7 @@ public interface RBAC {
      * extra request to Stytch. The policy will be refreshed if an authorization check is requested and the RBAC policy was
      * last updated more than 5 minutes ago.
      *
-     * Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/docs/dashboard/rbac) in the
+     * Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/dashboard/rbac) in the
      * Dashboard.
      * Additionally, [Role assignment](https://stytch.com/docs/b2b/guides/rbac/role-assignment) can be programmatically
      * managed through certain Stytch API endpoints.
@@ -49,7 +49,7 @@ public interface RBAC {
      * extra request to Stytch. The policy will be refreshed if an authorization check is requested and the RBAC policy was
      * last updated more than 5 minutes ago.
      *
-     * Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/docs/dashboard/rbac) in the
+     * Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/dashboard/rbac) in the
      * Dashboard.
      * Additionally, [Role assignment](https://stytch.com/docs/b2b/guides/rbac/role-assignment) can be programmatically
      * managed through certain Stytch API endpoints.
@@ -70,7 +70,7 @@ public interface RBAC {
      * extra request to Stytch. The policy will be refreshed if an authorization check is requested and the RBAC policy was
      * last updated more than 5 minutes ago.
      *
-     * Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/docs/dashboard/rbac) in the
+     * Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/dashboard/rbac) in the
      * Dashboard.
      * Additionally, [Role assignment](https://stytch.com/docs/b2b/guides/rbac/role-assignment) can be programmatically
      * managed through certain Stytch API endpoints.

@@ -315,15 +315,15 @@ public interface Sessions {
 
     /**
      * Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted
-     * Auth Token profile in the Stytch dashboard [here](https://stytch.com/docs/dashboard/trusted-auth-tokens).  If a session
+     * Auth Token profile in the Stytch dashboard [here](https://stytch.com/dashboard/trusted-auth-tokens).  If a session
      * token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing
      * session.
      */
     public suspend fun attest(data: AttestRequest): StytchResult<AttestResponse>
 
     /**
      * Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted
-     * Auth Token profile in the Stytch dashboard [here](https://stytch.com/docs/dashboard/trusted-auth-tokens).  If a session
+     * Auth Token profile in the Stytch dashboard [here](https://stytch.com/dashboard/trusted-auth-tokens).  If a session
      * token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing
      * session.
      */
@@ -334,7 +334,7 @@ public interface Sessions {
 
     /**
      * Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted
-     * Auth Token profile in the Stytch dashboard [here](https://stytch.com/docs/dashboard/trusted-auth-tokens).  If a session
+     * Auth Token profile in the Stytch dashboard [here](https://stytch.com/dashboard/trusted-auth-tokens).  If a session
      * token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing
      * session.
      */
@@ -343,8 +343,7 @@ public interface Sessions {
     /**
      * Migrate a session from an external OIDC compliant endpoint.
      * Stytch will call the external UserInfo endpoint defined in your Stytch Project settings in the
-     * [Dashboard](https://stytch.com/docs/dashboard), and then perform a lookup using the `session_token`. <!-- FIXME more
-     * specific dashboard link-->
+     * [Dashboard](https://stytch.com/dashboard/migrations), and then perform a lookup using the `session_token`.
      * If the response contains a valid email address, Stytch will attempt to match that email address with an existing Member
      * in your Organization and create a Stytch Session.
      * You will need to create the member before using this endpoint.
@@ -354,8 +353,7 @@ public interface Sessions {
     /**
      * Migrate a session from an external OIDC compliant endpoint.
      * Stytch will call the external UserInfo endpoint defined in your Stytch Project settings in the
-     * [Dashboard](https://stytch.com/docs/dashboard), and then perform a lookup using the `session_token`. <!-- FIXME more
-     * specific dashboard link-->
+     * [Dashboard](https://stytch.com/dashboard/migrations), and then perform a lookup using the `session_token`.
      * If the response contains a valid email address, Stytch will attempt to match that email address with an existing Member
      * in your Organization and create a Stytch Session.
      * You will need to create the member before using this endpoint.
@@ -368,8 +366,7 @@ public interface Sessions {
     /**
      * Migrate a session from an external OIDC compliant endpoint.
      * Stytch will call the external UserInfo endpoint defined in your Stytch Project settings in the
-     * [Dashboard](https://stytch.com/docs/dashboard), and then perform a lookup using the `session_token`. <!-- FIXME more
-     * specific dashboard link-->
+     * [Dashboard](https://stytch.com/dashboard/migrations), and then perform a lookup using the `session_token`.
      * If the response contains a valid email address, Stytch will attempt to match that email address with an existing Member
      * in your Organization and create a Stytch Session.
      * You will need to create the member before using this endpoint.

@@ -29,17 +29,23 @@ public interface TOTPs {
      * Create a new TOTP instance for a Member. The Member can use the authenticator application of their choice to scan the
      * QR code or enter the secret.
      *
-     * Passing an intermediate session token, session token, or session JWT is not required, but if passed must match the
-     * Member ID passed.
+     * If the Member already has an active MFA factor, then passing an intermediate session token, session token, or session
+     * JWT with the existing MFA factor on it is required to prevent bypassing MFA.
+     *
+     * Otherwise, passing an intermediate session token, session token, or session JWT is not required, but if passed must
+     * match the `member_id` passed.
      */
     public suspend fun create(data: CreateRequest): StytchResult<CreateResponse>
 
     /**
      * Create a new TOTP instance for a Member. The Member can use the authenticator application of their choice to scan the
      * QR code or enter the secret.
      *
-     * Passing an intermediate session token, session token, or session JWT is not required, but if passed must match the
-     * Member ID passed.
+     * If the Member already has an active MFA factor, then passing an intermediate session token, session token, or session
+     * JWT with the existing MFA factor on it is required to prevent bypassing MFA.
+     *
+     * Otherwise, passing an intermediate session token, session token, or session JWT is not required, but if passed must
+     * match the `member_id` passed.
      */
     public fun create(
         data: CreateRequest,
@@ -50,8 +56,11 @@ public interface TOTPs {
      * Create a new TOTP instance for a Member. The Member can use the authenticator application of their choice to scan the
      * QR code or enter the secret.
      *
-     * Passing an intermediate session token, session token, or session JWT is not required, but if passed must match the
-     * Member ID passed.
+     * If the Member already has an active MFA factor, then passing an intermediate session token, session token, or session
+     * JWT with the existing MFA factor on it is required to prevent bypassing MFA.
+     *
+     * Otherwise, passing an intermediate session token, session token, or session JWT is not required, but if passed must
+     * match the `member_id` passed.
      */
     public fun createCompletable(data: CreateRequest): CompletableFuture<StytchResult<CreateResponse>>