GITBOOK-97: change request with no subject merged in GitBook

docs/advanced/tokens.md

@@ -58,3 +58,28 @@ In the Pro version of Rollup you can set the issuer (iss) to your own custom dom
 Access tokens do not contain any user information other than their ID (sub claim) and authorization information about the actions the application is allowed to perform via the API (scope claim). This makes them useful for securing an API but not for authenticating a user.
 
 In some situations, it may be desirable to include additional information about the user or other custom claims in the access token to save the API from having to fetch details about the user. If you choose to do this, be aware that these extra claims will be readable in the access token. Non-access claims, however, will be readable in the ID token. To learn more, read [Create Custom Claims](custom-claims.md).
+
+## Refresh Tokens
+
+In addition to ID tokens and access tokens, OAuth 2.0 also introduces the concept of refresh tokens. A refresh token is a special kind of token that can be used to obtain a renewed access token. This is useful in situations where the access token has expired or has been invalidated, and the application needs to gain access to the user's resources without having to re-authenticate the user.
+
+Refresh tokens are typically long-lived and can be used to request new access tokens from the authorization server. This is done by sending a request to the token endpoint of the authorization server, including the refresh token along with the client's ID and secret.
+
+Here is an example of a refresh token:
+
+```json
+{
+  "iss": "https://passport.rollup.id/",
+  "aud": ["{yourClientId}"],
+  "sub": "{userId}",
+  "exp": "{expiryTimestamp}",
+  "iat": "{issuedAtTimestamp}",
+  "jti": "{uniqueTokenIdentifier}"
+}
+```
+
+In the Pro version of Rollup, you can set the issuer (iss) to your own custom domain. See the custom domain feature in your Console app.
+
+Refresh tokens provide a more seamless user experience by reducing the need for the user to re-authenticate and grant permissions, while also maintaining the security and privacy of the user's data. However, because refresh tokens can be used to obtain new access tokens, they must be stored securely and treated with the same level of care as the user's credentials.
+
+To learn more about using refresh tokens with Rollup ID, refer to our [API documentation](../reference/passport-api.md#exchange-token) and resources.

docs/guides/connecting-to-your-database.md

@@ -2,7 +2,7 @@
 description: How to connect users to your database
 ---
 
-# Adding Users to your Database
+# Storing Tokens
 
 After completing the [auth flow](../getting-started/auth-flow.md) and obtaining a user's ID token and access token, you can choose from several strategies to connect users to your app's database. For more information on the ID token, refer to the [Tokens](../advanced/tokens.md) documentation.
 
@@ -15,3 +15,22 @@ You can create a user in your database using the ID token. The ID token contains
 The access token also contains the user's unique identifier in the subject (sub) field. You can use this to identify the user in your database. Additionally, the access token includes the user's consented scopes, which help you determine the information you can access from the user's profile using the [Galaxy API](../reference/galaxy-api.md).
 
 Make sure to store the access token securely in your database or another safe storage mechanism accessible to your application.
+
+## Refresh Token
+
+In addition to storing ID tokens, you may also need to store refresh tokens in your database. Refresh tokens are used to obtain new access tokens without requiring the user to re-authenticate. This can be particularly useful for providing a seamless user experience, especially for applications that require long-lived sessions.
+
+When you receive a refresh token, it should be stored securely in your database, associated with the user. Here's an example of how you might store a refresh token:
+
+```json
+{
+  "userId": "{userId}",
+  "refreshToken": "{refreshToken}"
+}
+```
+
+When the access token expires, your application can use the stored refresh token to request a new access token from the Rollup ID authorization server. This request would include the refresh token along with your application's client ID and secret.
+
+It's important to handle refresh tokens securely because they can be used to obtain new access tokens. If a refresh token is leaked, it could potentially allow unauthorized access to the user's resources. Therefore, refresh tokens should be stored securely and treated with the same level of care as the user's credentials.
+
+To learn more about using refresh tokens with Rollup ID, refer to our [API documentation](../reference/passport-api.md) and resources.