stytch 10.18.0 → 10.20.0

data/lib/stytch/b2b_sessions.rb

@@ -231,15 +231,18 @@ module StytchB2B
 
     # Use this endpoint to exchange a's existing session for another session in a different. This can be used to accept an invite, but not to create a new member via domain matching.
     #
-    # To create a new member via domain matching, use the [Exchange Intermediate Session](https://stytch.com/docs/b2b/api/exchange-intermediate-session) flow instead.
+    # To create a new member via email domain, use the [Exchange Intermediate Session](https://stytch.com/docs/b2b/api/exchange-intermediate-session) flow instead.
     #
-    # Only Email Magic Link, OAuth, and SMS OTP factors can be transferred between sessions. Other authentication factors, such as password factors, will not be transferred to the new session.
-    # Any OAuth Tokens owned by the Member will not be transferred to the new Organization.
-    # SMS OTP factors can be used to fulfill MFA requirements for the target Organization if both the original and target Member have the same phone number and the phone number is verified for both Members.
-    # HubSpot and Slack OAuth registrations will not be transferred between sessions. Instead, you will receive a corresponding factor with type `"oauth_exchange_slack"` or `"oauth_exchange_hubspot"`
+    # If the user **has** already satisfied the authentication requirements of the Organization they are trying to switch into, this API will return `member_authenticated: true` and a `session_token` and `session_jwt`.
+    #
+    # If the user **has not** satisfied the primary or secondary authentication requirements of the Organization they are attempting to switch into, this API will return `member_authenticated: false` and an `intermediate_session_token`.
+    #
+    # If `primary_required` is set, prompt the user to fulfill the Organization's auth requirements using the options returned in `primary_required.allowed_auth_methods`.
+    #
+    # If `primary_required` is null and `mfa_required` is set, check `mfa_required.member_options` to determine if the Member has SMS OTP or TOTP set up for MFA and prompt accordingly. If the Member has SMS OTP, check `mfa_required.secondary_auth_initiated` to see if the OTP has already been sent.
+    #
+    # Include the `intermediate_session_token` returned above when calling the `authenticate()` method that the user needed to perform. Once the user has completed the authentication requirements they were missing, they will be granted a full `session_token` and `session_jwt` to indicate they have successfully logged into the Organization.
     #
-    # If the Member is required to complete MFA to log in to the Organization, the returned value of `member_authenticated` will be `false`, and an `intermediate_session_token` will be returned.
-    # The `intermediate_session_token` can be passed into the [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms) to complete the MFA step and acquire a full member session.
     # The `intermediate_session_token` can also be used with the [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session) or the [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to join a different Organization or create a new one.
     # The `session_duration_minutes` and `session_custom_claims` parameters will be ignored.
     #
@@ -290,9 +293,6 @@ module StytchB2B
     # member_id::
     #   Globally unique UUID that identifies a specific Member.
     #   The type of this field is +String+.
-    # member_session::
-    #   The [Session object](https://stytch.com/docs/b2b/api/session-object).
-    #   The type of this field is +MemberSession+ (+object+).
     # session_token::
     #   A secret token for a given Stytch Session.
     #   The type of this field is +String+.
@@ -314,11 +314,14 @@ module StytchB2B
     # status_code::
     #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
     #   The type of this field is +Integer+.
+    # member_session::
+    #   The [Session object](https://stytch.com/docs/b2b/api/session-object).
+    #   The type of this field is nilable +MemberSession+ (+object+).
     # mfa_required::
     #   Information about the MFA requirements of the Organization and the Member's options for fulfilling MFA.
     #   The type of this field is nilable +MfaRequired+ (+object+).
     # primary_required::
-    #   (no documentation yet)
+    #   Information about the primary authentication requirements of the Organization.
     #   The type of this field is nilable +PrimaryRequired+ (+object+).
     def exchange(
       organization_id:,
@@ -344,7 +347,9 @@ module StytchB2B
     # Use this endpoint to exchange a Connected Apps Access Token back into a Member Session for the underlying Member.
     # This session can be used with the Stytch SDKs and APIs.
     #
-    # The Access Token must contain the `full_access` scope and must not be more than 5 minutes old. Access Tokens may only be exchanged a single time.
+    # The Access Token must contain the `full_access` scope (only available to First Party clients) and must not be more than 5 minutes old. Access Tokens may only be exchanged a single time.
+    #
+    # The Member Session returned will be the same Member Session that was active in your application (the authorizing party) during the initial authorization flow.
     #
     # Because the Member previously completed MFA and satisfied all Organization authentication requirements at the time of the original Access Token issuance, this endpoint will never return an `intermediate_session_token` or require MFA.
     #
@@ -485,13 +490,13 @@ module StytchB2B
 
     # Get the JSON Web Key Set (JWKS) for a project.
     #
-    # JWKS are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key, and both keys will be returned by this endpoint for a period of 1 month.
+    # Within the JWKS, the JSON Web Keys are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key, and both keys will be returned by this endpoint for a period of 1 month.
     #
-    # JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old JWKS, and some JWTs will be signed by the new JWKS. The correct JWKS to use for validation is determined by matching the `kid` value of the JWT and JWKS.
+    # JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old keys, and some JWTs will be signed by the new keys. The correct key to use for validation is determined by matching the `kid` value of the JWT and key.
     #
-    # If you're using one of our [backend SDKs](https://stytch.com/docs/b2b/sdks), the JWKS rotation will be handled for you.
+    # If you're using one of our [backend SDKs](https://stytch.com/docs/b2b/sdks), the JSON Web Key (JWK) rotation will be handled for you.
     #
-    # If you're using your own JWT validation library, many have built-in support for JWKS rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWKS to use for validation by inspecting the `kid` value.
+    # If you're using your own JWT validation library, many have built-in support for JWK rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWK to use for validation by inspecting the `kid` value.
     #
     # See our [How to use Stytch Session JWTs](https://stytch.com/docs/b2b/guides/sessions/resources/using-jwts) guide for more information.
     #

data/lib/stytch/b2b_sso.rb

@@ -230,6 +230,9 @@ module StytchB2B
     # mfa_required::
     #   Information about the MFA requirements of the Organization and the Member's options for fulfilling MFA.
     #   The type of this field is nilable +MfaRequired+ (+object+).
+    # primary_required::
+    #   (no documentation yet)
+    #   The type of this field is nilable +PrimaryRequired+ (+object+).
     def authenticate(
       sso_token:,
       pkce_code_verifier: nil,

data/lib/stytch/crypto_wallets.rb

@@ -31,7 +31,7 @@ module Stytch
     #   The crypto wallet address to authenticate.
     #   The type of this field is +String+.
     # user_id::
-    #   The unique ID of a specific User. You may use an external_id here if one is set for the user.
+    #   The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
     #   The type of this field is nilable +String+.
     # session_token::
     #   The `session_token` associated with a User's existing Session.
@@ -139,7 +139,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     # siwe_params::

data/lib/stytch/fraud.rb

@@ -27,7 +27,7 @@ module Stytch
         @connection = connection
       end
 
-      # Lookup the associated fingerprint for the `telemetry_id` returned from the `GetTelemetryID` function. Learn more about the different fingerprint types and verdicts in our [DFP guide](https://stytch.com/docs/fraud/guides/device-fingerprinting/overview).
+      # Lookup the associated fingerprint for the `telemetry_id` returned from the `GetTelemetryID()` function. Learn more about the different fingerprint types and verdicts in our [DFP guide](https://stytch.com/docs/fraud/guides/device-fingerprinting/overview).
       #
       # Make a decision based on the returned `verdict`:
       # * `ALLOW` - This is a known valid device grouping or device profile that is part of the default `ALLOW` listed set of known devices by Stytch. This grouping is made up of  verified device profiles that match the characteristics of known/authentic traffic origins.

data/lib/stytch/impersonation.rb

@@ -49,7 +49,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def authenticate(

data/lib/stytch/magic_links.rb

@@ -30,7 +30,7 @@ module Stytch
     #       In the redirect URL, the `stytch_token_type` will be `magic_link`. See [here](https://stytch.com/docs/workspace-management/redirect-urls) for more detail.
     #   The type of this field is +String+.
     # attributes::
-    #   Provided attributes help with fraud detection.
+    #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
     #   The type of this field is nilable +Attributes+ (+object+).
     # options::
     #   Specify optional security settings.
@@ -90,7 +90,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def authenticate(
@@ -127,13 +127,13 @@ module Stytch
     #
     # == Parameters:
     # user_id::
-    #   The unique ID of a specific User. You may use an external_id here if one is set for the user.
+    #   The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
     #   The type of this field is +String+.
     # expiration_minutes::
     #   Set the expiration for the Magic Link `token` in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).
     #   The type of this field is nilable +Integer+.
     # attributes::
-    #   Provided attributes help with fraud detection.
+    #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
     #   The type of this field is nilable +Attributes+ (+object+).
     #
     # == Returns:
@@ -188,7 +188,7 @@ module Stytch
       #   Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Login.
       #   The type of this field is nilable +String+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # login_magic_link_url::
       #   The URL the end user clicks from the login Email Magic Link. This should be a URL that your app receives and parses and subsequently send an API request to authenticate the Magic Link and log in the User. If this value is not passed, the default login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.
@@ -206,7 +206,7 @@ module Stytch
       #   A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device.
       #   The type of this field is nilable +String+.
       # user_id::
-      #   The unique ID of a specific User. You may use an external_id here if one is set for the user.
+      #   The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
       #   The type of this field is nilable +String+.
       # session_token::
       #   The `session_token` of the user to associate the email with.
@@ -303,7 +303,7 @@ module Stytch
       #   Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Sign-up.
       #   The type of this field is nilable +String+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # create_user_as_pending::
       #   Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false.
@@ -385,7 +385,7 @@ module Stytch
       #   Use a custom template for invite emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Invite.
       #   The type of this field is nilable +String+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # name::
       #   The name of the user. Each field in the name object is optional.
@@ -404,6 +404,12 @@ module Stytch
       # Request support for additional languages [here](https://docs.google.com/forms/d/e/1FAIpQLScZSpAu_m2AmLXRT3F3kap-s_mcV6UTBitYn6CdyWP0-o7YjQ/viewform?usp=sf_link")!
       #
       #   The type of this field is nilable +InviteRequestLocale+ (string enum).
+      # trusted_metadata::
+      #   The `trusted_metadata` field contains an arbitrary JSON object of application-specific data. See the [Metadata](https://stytch.com/docs/api/metadata) reference for complete field behavior details.
+      #   The type of this field is nilable +object+.
+      # untrusted_metadata::
+      #   The `untrusted_metadata` field contains an arbitrary JSON object of application-specific data. Untrusted metadata can be edited by end users directly via the SDK, and **cannot be used to store critical information.** See the [Metadata](https://stytch.com/docs/api/metadata) reference for complete field behavior details.
+      #   The type of this field is nilable +object+.
       #
       # == Returns:
       # An object with the following fields:
@@ -426,7 +432,9 @@ module Stytch
         name: nil,
         invite_magic_link_url: nil,
         invite_expiration_minutes: nil,
-        locale: nil
+        locale: nil,
+        trusted_metadata: nil,
+        untrusted_metadata: nil
       )
         headers = {}
         request = {
@@ -438,6 +446,8 @@ module Stytch
         request[:invite_magic_link_url] = invite_magic_link_url unless invite_magic_link_url.nil?
         request[:invite_expiration_minutes] = invite_expiration_minutes unless invite_expiration_minutes.nil?
         request[:locale] = locale unless locale.nil?
+        request[:trusted_metadata] = trusted_metadata unless trusted_metadata.nil?
+        request[:untrusted_metadata] = untrusted_metadata unless untrusted_metadata.nil?
 
         post_request('/v1/magic_links/email/invite', request, headers)
       end

data/lib/stytch/oauth.rb

@@ -29,7 +29,7 @@ module Stytch
     #   The OAuth provider's name.
     #   The type of this field is +String+.
     # user_id::
-    #   The unique ID of a specific User. You may use an external_id here if one is set for the user.
+    #   The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
     #   The type of this field is nilable +String+.
     # session_token::
     #   The `session_token` associated with a User's existing Session.
@@ -142,7 +142,7 @@ module Stytch
     # user_session::
     #   A `Session` object. For backwards compatibility reasons, the session from an OAuth authenticate call is labeled as `user_session`, but is otherwise just a standard stytch `Session` object.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def authenticate(

data/lib/stytch/otps.rb

@@ -31,7 +31,7 @@ module Stytch
     #   The code to authenticate.
     #   The type of this field is +String+.
     # attributes::
-    #   Provided attributes help with fraud detection.
+    #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
     #   The type of this field is nilable +Attributes+ (+object+).
     # options::
     #   Specify optional security settings.
@@ -88,7 +88,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def authenticate(
@@ -150,7 +150,7 @@ module Stytch
       #   Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
       #   The type of this field is nilable +Integer+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # locale::
       #   Used to determine which language to use when sending the user this delivery method. Parameter is a [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`.
@@ -161,7 +161,7 @@ module Stytch
       #
       #   The type of this field is nilable +SendRequestLocale+ (string enum).
       # user_id::
-      #   The unique ID of a specific User. You may use an external_id here if one is set for the user.
+      #   The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
       #   The type of this field is nilable +String+.
       # session_token::
       #   The `session_token` associated with a User's existing Session.
@@ -228,7 +228,7 @@ module Stytch
       #   Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
       #   The type of this field is nilable +Integer+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # create_user_as_pending::
       #   Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false.
@@ -313,7 +313,7 @@ module Stytch
       #   Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
       #   The type of this field is nilable +Integer+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # locale::
       #   Used to determine which language to use when sending the user this delivery method. Parameter is a [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`.
@@ -324,7 +324,7 @@ module Stytch
       #
       #   The type of this field is nilable +SendRequestLocale+ (string enum).
       # user_id::
-      #   The unique ID of a specific User. You may use an external_id here if one is set for the user.
+      #   The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
       #   The type of this field is nilable +String+.
       # session_token::
       #   The `session_token` associated with a User's existing Session.
@@ -387,7 +387,7 @@ module Stytch
       #   Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
       #   The type of this field is nilable +Integer+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # create_user_as_pending::
       #   Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false.
@@ -465,7 +465,7 @@ module Stytch
       #   Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
       #   The type of this field is nilable +Integer+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # locale::
       #   Used to determine which language to use when sending the user this delivery method. Parameter is a [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`.
@@ -476,7 +476,7 @@ module Stytch
       #
       #   The type of this field is nilable +SendRequestLocale+ (string enum).
       # user_id::
-      #   The unique ID of a specific User. You may use an external_id here if one is set for the user.
+      #   The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
       #   The type of this field is nilable +String+.
       # session_token::
       #   The `session_token` associated with a User's existing Session.
@@ -546,7 +546,7 @@ module Stytch
       #   Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
       #   The type of this field is nilable +Integer+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # create_user_as_pending::
       #   Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false.

data/lib/stytch/passwords.rb

@@ -34,7 +34,7 @@ module Stytch
     #   The email address of the end user.
     #   The type of this field is +String+.
     # password::
-    #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characers, etc.
+    #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characters, etc.
     #   The type of this field is +String+.
     # session_duration_minutes::
     #   Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist,
@@ -88,7 +88,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def create(
@@ -127,7 +127,7 @@ module Stytch
     #   The email address of the end user.
     #   The type of this field is +String+.
     # password::
-    #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characers, etc.
+    #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characters, etc.
     #   The type of this field is +String+.
     # session_token::
     #   The `session_token` associated with a User's existing Session.
@@ -175,7 +175,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def authenticate(
@@ -214,7 +214,7 @@ module Stytch
     #
     # == Parameters:
     # password::
-    #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characers, etc.
+    #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characters, etc.
     #   The type of this field is +String+.
     # email::
     #   The email address of the end user.
@@ -308,7 +308,7 @@ module Stytch
     #    the user owns the phone number in question. Access to this field is restricted. To enable it, please send us a note at support@stytch.com.
     #   The type of this field is nilable +Boolean+.
     # external_id::
-    #   If a new user is created, this will set an identifier that can be used in API calls wherever a user_id is expected. This is a string consisting of alphanumeric, `.`, `_`, `-`, or `|` characters with a maximum length of 128 characters. External IDs must be unique within an organization, but may be reused across different organizations in the same project. Note that if a user already exists, this field will be ignored.
+    #   If a new user is created, this will set an identifier that can be used in API calls wherever a user_id is expected. This is a string consisting of alphanumeric, `.`, `_`, `-`, or `|` characters with a maximum length of 128 characters.
     #   The type of this field is nilable +String+.
     #
     # == Returns:
@@ -398,7 +398,7 @@ module Stytch
       #   A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device.
       #   The type of this field is nilable +String+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # login_redirect_url::
       #   The URL Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be a route in your application which will run `oauth.authenticate` (see below) and finish the login.
@@ -472,7 +472,7 @@ module Stytch
       #       See examples and read more about redirect URLs [here](https://stytch.com/docs/workspace-management/redirect-urls).
       #   The type of this field is +String+.
       # password::
-      #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characers, etc.
+      #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characters, etc.
       #   The type of this field is +String+.
       # session_token::
       #   The `session_token` associated with a User's existing Session.
@@ -500,7 +500,7 @@ module Stytch
       #   Custom claims made with reserved claims ("iss", "sub", "aud", "exp", "nbf", "iat", "jti") will be ignored. Total custom claims size cannot exceed four kilobytes.
       #   The type of this field is nilable +object+.
       # attributes::
-      #   Provided attributes help with fraud detection.
+      #   Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
       #   The type of this field is nilable +Attributes+ (+object+).
       # options::
       #   Specify optional security settings.
@@ -529,7 +529,7 @@ module Stytch
       # session::
       #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
       #
-      #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+      #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
       #
       #   The type of this field is nilable +Session+ (+object+).
       def reset(
@@ -627,7 +627,7 @@ module Stytch
       # session::
       #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
       #
-      #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+      #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
       #
       #   The type of this field is nilable +Session+ (+object+).
       def reset(
@@ -667,7 +667,7 @@ module Stytch
       #
       # == Parameters:
       # password::
-      #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characers, etc.
+      #   The password for the user. Any UTF8 character is allowed, e.g. spaces, emojis, non-English characters, etc.
       #   The type of this field is +String+.
       # session_token::
       #   The `session_token` associated with a User's existing Session.
@@ -715,7 +715,7 @@ module Stytch
       # session::
       #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
       #
-      #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+      #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
       #
       #   The type of this field is nilable +Session+ (+object+).
       def reset(

data/lib/stytch/sessions.rb

@@ -37,7 +37,7 @@ module Stytch
     #
     # == Parameters:
     # user_id::
-    #   The `user_id` to get active Sessions for. You may use an external_id here if one is set for the user.
+    #   The `user_id` to get active Sessions for. You may use an `external_id` here if one is set for the user.
     #   The type of this field is +String+.
     #
     # == Returns:
@@ -46,7 +46,7 @@ module Stytch
     #   Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
     #   The type of this field is +String+.
     # sessions::
-    #   An array of Session objects.
+    #   An array of [Session objects](https://stytch.com/docs/api/session-object).
     #   The type of this field is list of +Session+ (+object+).
     # status_code::
     #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
@@ -90,7 +90,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is +Session+ (+object+).
     # session_token::
@@ -202,7 +202,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def migrate(
@@ -223,7 +223,9 @@ module Stytch
     # Use this endpoint to exchange a Connected Apps Access Token back into a Stytch Session for the underlying User.
     # This session can be used with the Stytch SDKs and APIs.
     #
-    # The Access Token must contain the `full_access` scope and must not be more than 5 minutes old. Access Tokens may only be exchanged a single time.
+    # The Session returned will be the same Session that was active in your application (the authorizing party) during the initial authorization flow.
+    #
+    # The Access Token must contain the `full_access` scope (only available to First Party clients) and must not be more than 5 minutes old. Access Tokens may only be exchanged a single time.
     #
     # == Parameters:
     # access_token::
@@ -269,7 +271,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def exchange_access_token(
@@ -289,13 +291,13 @@ module Stytch
 
     # Get the JSON Web Key Set (JWKS) for a project.
     #
-    # JWKS are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key, and both keys will be returned by this endpoint for a period of 1 month.
+    # Within the JWKS, the JSON Web Keys are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key, and both keys will be returned by this endpoint for a period of 1 month.
     #
-    # JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old JWKS, and some JWTs will be signed by the new JWKS. The correct JWKS to use for validation is determined by matching the `kid` value of the JWT and JWKS.
+    # JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old keys, and some JWTs will be signed by the new keys. The correct key to use for validation is determined by matching the `kid` value of the JWT and key.
     #
-    # If you're using one of our [backend SDKs](https://stytch.com/docs/sdks), the JWKS rotation will be handled for you.
+    # If you're using one of our [backend SDKs](https://stytch.com/docs/b2b/sdks), the JSON Web Key (JWK) rotation will be handled for you.
     #
-    # If you're using your own JWT validation library, many have built-in support for JWKS rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWKS to use for validation by inspecting the `kid` value.
+    # If you're using your own JWT validation library, many have built-in support for JWK rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWK to use for validation by inspecting the `kid` value.
     #
     # See our [How to use Stytch Session JWTs](https://stytch.com/docs/guides/sessions/using-jwts) guide for more information.
     #

data/lib/stytch/totps.rb

@@ -20,7 +20,7 @@ module Stytch
     #
     # == Parameters:
     # user_id::
-    #   The `user_id` of an active user the TOTP registration should be tied to. You may use an external_id here if one is set for the user.
+    #   The `user_id` of an active user the TOTP registration should be tied to. You may use an `external_id` here if one is set for the user.
     #   The type of this field is +String+.
     # expiration_minutes::
     #   The expiration for the TOTP instance. If the newly created TOTP is not authenticated within this time frame the TOTP will be unusable. Defaults to 1440 (1 day) with a minimum of 5 and a maximum of 1440.
@@ -69,7 +69,7 @@ module Stytch
     #
     # == Parameters:
     # user_id::
-    #   The `user_id` of an active user the TOTP registration should be tied to. You may use an external_id here if one is set for the user.
+    #   The `user_id` of an active user the TOTP registration should be tied to. You may use an `external_id` here if one is set for the user.
     #   The type of this field is +String+.
     # totp_code::
     #   The TOTP code to authenticate. The TOTP code should consist of 6 digits.
@@ -123,7 +123,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def authenticate(
@@ -151,7 +151,7 @@ module Stytch
     #
     # == Parameters:
     # user_id::
-    #   The `user_id` of an active user the TOTP registration should be tied to. You may use an external_id here if one is set for the user.
+    #   The `user_id` of an active user the TOTP registration should be tied to. You may use an `external_id` here if one is set for the user.
     #   The type of this field is +String+.
     #
     # == Returns:
@@ -183,7 +183,7 @@ module Stytch
     #
     # == Parameters:
     # user_id::
-    #   The `user_id` of an active user the TOTP registration should be tied to. You may use an external_id here if one is set for the user.
+    #   The `user_id` of an active user the TOTP registration should be tied to. You may use an `external_id` here if one is set for the user.
     #   The type of this field is +String+.
     # recovery_code::
     #   The recovery code to authenticate.
@@ -237,7 +237,7 @@ module Stytch
     # session::
     #   If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.
     #
-    #   See [GET sessions](https://stytch.com/docs/api/session-get) for complete response fields.
+    #   See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.
     #
     #   The type of this field is nilable +Session+ (+object+).
     def recover(