Add B2B step-up docs and mark email_id as optional for OAuth factors (#…

…307)

lib/b2b/discovery_intermediate_sessions.ts

@@ -15,16 +15,14 @@ import { request } from "../shared";
 export interface B2BDiscoveryIntermediateSessionsExchangeRequest {
   /**
    * The Intermediate Session Token. This token does not necessarily belong to a specific instance of a
-   * Member, but represents a bag of factors that may be converted to a member session.
-   *     The token can be used with the
-   * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *     or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete an MFA flow;
-   *     the
+   * Member, but represents a bag of factors that may be converted to a member session. The token can be used
+   * with the [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
    * to join a specific Organization that allows the factors represented by the intermediate session token;
-   *     or the
+   * or the
    * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token: string;
@@ -102,17 +100,16 @@ export interface B2BDiscoveryIntermediateSessionsExchangeResponse {
   member_authenticated: boolean;
   /**
    * The returned Intermediate Session Token is identical to the one that was originally passed in to the
-   * request.
-   *       The token can be used with the
+   * request. If this value is non-empty, the member must complete an MFA step to finish logging in to the
+   * Organization. The token can be used with the
    * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *       or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete the MFA flow and log in to the Organization.
-   *       It can also be used with the
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
-   * to join a different existing Organization,
-   *       or the
-   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization.
+   * to join a specific Organization that allows the factors represented by the intermediate session token;
+   * or the
+   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token: string;
   /**

lib/b2b/discovery_organizations.ts

@@ -20,16 +20,14 @@ import { request } from "../shared";
 export interface B2BDiscoveryOrganizationsCreateRequest {
   /**
    * The Intermediate Session Token. This token does not necessarily belong to a specific instance of a
-   * Member, but represents a bag of factors that may be converted to a member session.
-   *     The token can be used with the
-   * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *     or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete an MFA flow;
-   *     the
+   * Member, but represents a bag of factors that may be converted to a member session. The token can be used
+   * with the [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
    * to join a specific Organization that allows the factors represented by the intermediate session token;
-   *     or the
+   * or the
    * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token: string;
@@ -208,17 +206,16 @@ export interface B2BDiscoveryOrganizationsCreateResponse {
   member_authenticated: boolean;
   /**
    * The returned Intermediate Session Token is identical to the one that was originally passed in to the
-   * request.
-   *       The token can be used with the
+   * request. If this value is non-empty, the member must complete an MFA step to finish logging in to the
+   * Organization. The token can be used with the
    * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *       or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete the MFA flow and log in to the Organization.
-   *       It can also be used with the
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
-   * to join a different existing Organization,
-   *       or the
-   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization.
+   * to join a specific Organization that allows the factors represented by the intermediate session token;
+   * or the
+   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token: string;
   /**
@@ -239,16 +236,14 @@ export interface B2BDiscoveryOrganizationsCreateResponse {
 export interface B2BDiscoveryOrganizationsListRequest {
   /**
    * The Intermediate Session Token. This token does not necessarily belong to a specific instance of a
-   * Member, but represents a bag of factors that may be converted to a member session.
-   *     The token can be used with the
-   * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *     or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete an MFA flow;
-   *     the
+   * Member, but represents a bag of factors that may be converted to a member session. The token can be used
+   * with the [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
    * to join a specific Organization that allows the factors represented by the intermediate session token;
-   *     or the
+   * or the
    * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token?: string;

lib/b2b/magic_links.ts

@@ -78,6 +78,12 @@ export interface B2BMagicLinksAuthenticateRequest {
    *
    */
   locale?: "en" | "es" | "pt-br" | string;
+  /**
+   * Adds this primary authentication factor to the intermediate session token. If the resulting set of
+   * factors satisfies the organization's primary authentication requirements and MFA requirements, the
+   * intermediate session token will be consumed and converted to a member session. If not, the same
+   * intermediate session token will be returned.
+   */
   intermediate_session_token?: string;
 }
 
@@ -116,17 +122,16 @@ export interface B2BMagicLinksAuthenticateResponse {
   organization: Organization;
   /**
    * The returned Intermediate Session Token contains an Email Magic Link factor associated with the Member's
-   * email address.
-   *       The token can be used with the
+   * email address. If this value is non-empty, the member must complete an MFA step to finish logging in to
+   * the Organization. The token can be used with the
    * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *       or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete the MFA flow and log in to the Organization.
-   *       It can also be used with the
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
-   * to join a different existing Organization that allows login with Email Magic Links,
-   *       or the
-   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization.
+   * to join a specific Organization that allows the factors represented by the intermediate session token;
+   * or the
+   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token: string;
   /**

lib/b2b/magic_links_discovery.ts

@@ -26,16 +26,14 @@ export interface B2BMagicLinksDiscoveryAuthenticateResponse {
   request_id: string;
   /**
    * The Intermediate Session Token. This token does not necessarily belong to a specific instance of a
-   * Member, but represents a bag of factors that may be converted to a member session.
-   *     The token can be used with the
-   * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *     or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete an MFA flow;
-   *     the
+   * Member, but represents a bag of factors that may be converted to a member session. The token can be used
+   * with the [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
    * to join a specific Organization that allows the factors represented by the intermediate session token;
-   *     or the
+   * or the
    * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token: string;

lib/b2b/oauth.ts

@@ -20,7 +20,10 @@ export interface B2BOAuthProviderValues {
    * are included by default and how to add custom scopes.
    */
   scopes: string[];
-  // The `refresh_token` that you may use to refresh a User's session within the provider's API.
+  /**
+   * The `refresh_token` that you may use to obtain a new `access_token` for the User within the provider's
+   * API.
+   */
   refresh_token?: string;
   expires_at?: string;
   /**
@@ -85,6 +88,12 @@ export interface B2BOAuthAuthenticateRequest {
    *
    */
   locale?: "en" | "es" | "pt-br" | string;
+  /**
+   * Adds this primary authentication factor to the intermediate session token. If the resulting set of
+   * factors satisfies the organization's primary authentication requirements and MFA requirements, the
+   * intermediate session token will be consumed and converted to a member session. If not, the same
+   * intermediate session token will be returned.
+   */
   intermediate_session_token?: string;
 }
 
@@ -128,17 +137,16 @@ export interface B2BOAuthAuthenticateResponse {
   member_authenticated: boolean;
   /**
    * The returned Intermediate Session Token contains an OAuth factor associated with the Member's email
-   * address.
-   *       The token can be used with the
+   * address. If this value is non-empty, the member must complete an MFA step to finish logging in to the
+   * Organization. The token can be used with the
    * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *       or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete the MFA flow and log in to the Organization.
-   *       It can also be used with the
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
-   * to join a different existing Organization that allows login with OAuth,
-   *       or the
-   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization.
+   * to join a specific Organization that allows the factors represented by the intermediate session token;
+   * or the
+   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token: string;
   /**

lib/b2b/oauth_discovery.ts

@@ -30,16 +30,14 @@ export interface B2BOAuthDiscoveryAuthenticateResponse {
   request_id: string;
   /**
    * The Intermediate Session Token. This token does not necessarily belong to a specific instance of a
-   * Member, but represents a bag of factors that may be converted to a member session.
-   *     The token can be used with the
-   * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
-   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp),
-   *     or [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to
-   * complete an MFA flow;
-   *     the
+   * Member, but represents a bag of factors that may be converted to a member session. The token can be used
+   * with the [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms),
+   * [TOTP Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-totp), or
+   * [Recovery Codes Recover endpoint](https://stytch.com/docs/b2b/api/recovery-codes-recover) to complete an
+   * MFA flow and log in to the Organization. It can also be used with the
    * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
    * to join a specific Organization that allows the factors represented by the intermediate session token;
-   *     or the
+   * or the
    * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
    */
   intermediate_session_token: string;