FusionAuth · robotdan · Jan 14, 2025
@@ -110,6 +110,15 @@ import Xmlsignaturec14nmethodValues from 'src/content/docs/_shared/_xmlSignature
     * `SlidingWindow` - the expiration is calculated from the last time the token was used.
     * `SlidingWindowWithMaximumLifetime` - the expiration is calculated from the last time the token was used, or until the <InlineField>maximumTimeToLiveInMinutes</InlineField> is reached. <span class="text-green-600">Available since 1.46.0</span>
   </APIField>
+
+  <APIField name="application.jwtConfiguration.refreshTokenOneTimeUseConfiguration.gracePeriodInSeconds" type="Integer" optional defaults="0" since="1.55.0">
+    The length of time specified in seconds that a one time use token can be re-used.
+
+    This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period.
+
+    Note that one-time use tokens refreshed within a grace period are not considered for revocation when <InlineField>tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse</InlineField> is `true`. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated.
+  </APIField>
+
   <APIField name="application.jwtConfiguration.refreshTokenSlidingWindowConfiguration.maximumTimeToLiveInMinutes" type="Integer" defaults="43,200" optional since="1.46.0">
     The maximum lifetime of a refresh token when using a <InlineField>refreshTokenExpirationPolicy</InlineField> of `SlidingWindowWithMaximumLifetime`. Value must be greater than 0.
 

@@ -104,6 +104,14 @@ import Xmlsignaturec14nmethodValues from 'src/content/docs/_shared/_xmlSignature
     * `SlidingWindowWithMaximumLifetime` - the expiration is calculated from the last time the token was used, or until the <InlineField>maximumTimeToLiveInMinutes</InlineField> is reached. <span class="text-green-600">Available since 1.46.0</span>
   </APIField>
 
+  <APIField name={ props.base_field_name + ".jwtConfiguration.refreshTokenOneTimeUseConfiguration.gracePeriodInSeconds" } type="Integer" since="1.55.0">
+    The length of time specified in seconds that a one time use token can be re-used.
+
+    This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period.
+
+    Note that one-time use tokens refreshed within a grace period are not considered for revocation when <InlineField>tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse</InlineField> is `true`. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated.
+  </APIField>
+
   <APIField name={ props.base_field_name + ".jwtConfiguration.refreshTokenSlidingWindowConfiguration.maximumTimeToLiveInMinutes" } type="Integer" since="1.46.0">
     The maximum lifetime of a refresh token when using a <InlineField>refreshTokenExpirationPolicy</InlineField> of `SlidingWindowWithMaximumLifetime`.
   </APIField>

@@ -433,6 +433,14 @@ import TransactionTypes from 'src/content/docs/apis/_transaction-types.mdx';
     * `SlidingWindowWithMaximumLifetime` - the expiration is calculated from the last time the token was used, or until the <InlineField>maximumTimeToLiveInMinutes</InlineField> is reached. &nbsp; <AvailableSince since="1.46.0"/>
   </APIField>
 
+  <APIField name="tenant.jwtConfiguration.refreshTokenOneTimeUseConfiguration.gracePeriodInSeconds" type="Integer" optional defaults="0" since="1.55.0">
+    The length of time specified in seconds that a one time use token can be re-used.
+
+    This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period.
+
+    Note that one-time use tokens refreshed within a grace period are not considered for revocation when <InlineField>tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse</InlineField> is `true`. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated.
+  </APIField>
+
   <APIField name="tenant.jwtConfiguration.refreshTokenRevocationPolicy.onLoginPrevented" type="Boolean" optional defaults="true" since="1.17.0">
     When enabled, all refresh tokens will be revoked when a user action, such as locking an account based on a number of failed login attempts, prevents user login.
   </APIField>
@@ -441,6 +449,10 @@ import TransactionTypes from 'src/content/docs/apis/_transaction-types.mdx';
     When enabled, all refresh tokens will be revoked when a user enables multi-factor authentication for the first time. This policy will not be applied when adding subsequent multi-factor methods to the user.
   </APIField>
 
+  <APIField name="tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse" type="Boolean" optional defaults="false" since="1.55.0">
+    When enabled, if a one-time use refresh token is reused, the token will be revoked. This does not cause all refresh tokens to be revoked, only the reused token is revoked.
+  </APIField>
+
   <APIField name="tenant.jwtConfiguration.refreshTokenRevocationPolicy.onPasswordChanged" type="Boolean" optional defaults="true" since="1.17.0">
     When enabled, all refresh tokens will be revoked when a user changes their password.
   </APIField>

@@ -345,6 +345,14 @@ import JSON from 'src/components/JSON.astro';
     * `SlidingWindowWithMaximumLifetime` - the expiration is calculated from the last time the token was used, or until the <InlineField>maximumTimeToLiveInMinutes</InlineField> is reached. &nbsp; <AvailableSince since="1.46.0"/>
   </APIField>
 
+  <APIField name={ props.base_field_name + ".jwtConfiguration.refreshTokenOneTimeUseConfiguration.gracePeriodInSeconds" } type="Integer" since="1.55.0">
+    The length of time specified in seconds that a one time use token can be re-used.
+
+    This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period.
+
+    Note that one-time use tokens refreshed within a grace period are not considered for revocation when <InlineField>tenant.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse</InlineField> is `true`. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated.
+  </APIField>
+
   <APIField name={props.base_field_name + '.jwtConfiguration.refreshTokenRevocationPolicy.onLoginPrevented'} type="Boolean" since="1.17.0">
     When enabled, all refresh tokens will be revoked when a user action, such as locking an account based on a number of failed login attempts, prevents user login.
   </APIField>
@@ -353,6 +361,10 @@ import JSON from 'src/components/JSON.astro';
     When enabled, all refresh tokens will be revoked when a user enables multi-factor authentication for the first time. This policy will not be applied when adding subsequent multi-factor methods to the user.
   </APIField>
 
+  <APIField name={props.base_field_name + '.jwtConfiguration.refreshTokenRevocationPolicy.onOneTimeTokenReuse'} type="Boolean" since="1.55.0">
+    When enabled, if a one-time use refresh token is reused, the token will be revoked. This does not cause all refresh tokens to be revoked, only the reused token is revoked.
+  </APIField>
+
   <APIField name={props.base_field_name + '.jwtConfiguration.refreshTokenRevocationPolicy.onPasswordChanged'} type="Boolean" since="1.17.0">
     When enabled, all refresh tokens will be revoked when a user changes their password.
   </APIField>

@@ -10,6 +10,7 @@ import AdvancedPlanBlurb from 'src/content/docs/_shared/_advanced-plan-blurb.ast
 import APIBlock from 'src/components/api/APIBlock.astro';
 import APIField from 'src/components/api/APIField.astro';
 import Aside from 'src/components/Aside.astro';
+import AvailableSince from 'src/components/api/AvailableSince.astro';
 import InlineField from 'src/components/InlineField.astro';
 import LambdaTypes from 'src/content/docs/_shared/_lambda-types.astro';
 import MembershipLambda from 'src/content/docs/extend/code/_membership-lambda.md';
@@ -80,6 +81,28 @@ headers: new Headers([
 ])
 ```
 
+## Options
+
+### Timeouts
+
+<Aside type="version">
+  Available Since Version 1.55.0
+</Aside>
+
+In general you will want to be certain that any external request you make within a lambda function returns quickly. The duration of the request will be cause additional latency during the FusionAuth request and can reduce the performance of FusionAuth and cause unexpected errors.
+
+However, in some cases where you know a request may be slow, or the performance of the request is secondary to the request completing, you may need to extend these timeouts. These values are specified in milliseconds.
+
+By default, the HTTP read and connect timeouts are set to 2 seconds. The following is an example of setting the `connectTimeout` and the `readTimeout` on the HTTP request.
+
+```javascript
+var response = fetch("https://api.example.com/api/status", {
+    method: "GET",
+    connectTimeout: 42000,   // 42,000 ms, or 42 seconds
+    readTimeout: 42000       // 42,000 ms, or 42 seconds
+  });
+```
+
 ## Response
 
 A response object will be returned. It will have the following fields:
@@ -98,7 +121,7 @@ A response object will be returned. It will have the following fields:
 
 ## Securing API Keys In Lambdas
 
-Being able to make API requests against FusionAuth can be useful, but requires an API key to be stored in the Lambda code. 
+Being able to make API requests against FusionAuth can be useful, but requires an API key to be stored in the Lambda code.
 
 To secure that API key, you should:
 

@@ -14,6 +14,15 @@ import InlineField from 'src/components/InlineField.astro';
   <APIField name="Refresh token usage" optional defaults="Reusable">
     The <InlineField>Refresh token usage</InlineField> may be reusable or one time use. By default, a token is reusable and the token does not change after it was issued. With a one time use token, the token value will be changed each time the token is used to refresh a JWT. This means the client must store the new value after each use.
   </APIField>
+  <APIField name="One-time use grace period" optional defaults="0">
+    When <InlineField>Refresh token usage</InlineField> is set to `Reusable`, you may optionally set the grace period to something greater than `0` seconds.
+
+    The grace period is the length of time specified in seconds that a one time use token can be re-used.
+
+    This value must be greater than `0` and less than `86,400` which is equal to 24 hours. Setting this value to `0` effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past `0` to improve reliability for an asynchronous or clustered integration that may require a brief grace period.
+
+    Note that one-time use tokens refreshed within a grace period are not considered for revocation when the Tenant Refresh Token Revocation Policy is configured to revoke a one-time use refresh token on re-use. When a token is re-used within the grace period the current token will be returned on the API response and the token will not be rotated.
+  </APIField>
   <APIField name="Refresh token revocation" optional renderif={props.page === "tenant"}>
     The event or events that will cause refresh tokens to be revoked.
   </APIField>