Add additional information about specific customizations

v2/.gitignore

@@ -22,3 +22,4 @@ yarn-error.log*
 src/plugins/codeTypeChecking/javaEnv/snippets/*
 src/plugins/codeTypeChecking/phpEnv/snippets/*
 src/plugins/codeTypeChecking/pythonEnv/snippets/*
+src/plugins/codeTypeChecking/csharpEnv/snippets/*

v2/oauth/machine-to-machine-authentication.mdx

@@ -74,16 +74,17 @@ curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
       "tokenEndpointAuthMethod": "none",
       "client_name": "<YOUR_CLIENT_NAME>",
       "grant_types": ["client_credentials"],
+      "scope": "<custom_scope_1> <custom_scope_2>",
       "audience": ["<AUDIENCE_NAME>"]
     }'
 ```
 
 
-
 - `client_name` - Then name of the client that will be used later for identification.
 - `grant_types` - The grant types that the [**Client**](/introduction#client) will use. 
     - `client_credentials`: Allows the client to directly request an Access Token by authenticating itself with the Authorization Server using its own client credentials.
 - `audience` - Value used to identify for whom a token was issued. When a service will request an **OAuth2 Token** that can be used on this client, the requested token should include one of the audience values.
+- `scope` -  A space separated string of scopes that the [**Client**](/docs/oauth/introduction#client) will request access to.
 
 If the creation was successful, the API will return a response that looks like this:
 
@@ -99,6 +100,14 @@ If the creation was successful, the API will return a response that looks like t
 
 Based on the client creation process we can also infer the `authorization_url` value which is `^{form_apiDomain}^{form_apiBasePath}oauth/auth`. We will use this later on.
 
+### Change the default token lifespan
+
+By default, the token used in the authorization flow will have a 1 hour lifespan.
+
+If you want to change it you will need to set the `client_credentials_grant_access_token_lifespan` property in the [**Client**](/docs/oauth/introduction#client) creation request body.
+Use string values that signify time duration in milliecoseconds, seconds, minutes or hours (e.g. `"2000ms"`, `"60s"`, `"30m"`, `"1h"`).
+
+
 ## 3. Set Up your Authorization Service 
 
 In your [**Authorization Service**](/docs/oauth/introduction#authorization-service) backend you will need to initialize the **OAuth2Provider** recipe.

v2/oauth/multiple-frontends-with-a-single-backend.mdx

@@ -85,7 +85,8 @@ curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
       "response_types": ["code"],
       "grant_types": ["authorization_code", "refresh_token"],
       "tokenEndpointAuthMethod": "none",
-      "redirect_uri": ["https://<YOUR_APPLICATION_DOMAIN>/oauth/callback"]
+      "scope": "offline_access <custom_scope_1> <custom_scope_2>",
+      "redirect_uri": ["https://<YOUR_APPLICATION_DOMAIN>/oauth/callback"],
     }'
 ```
 
@@ -96,6 +97,9 @@ curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
     - `authorization_code`: Allows exchanging the **Authorization Code** for an [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
     - `refresh_token`: Allows exchanging the [**OAuth2 Refresh Token**](/docs/oauth/introduction#oauth2-refresh-token) for a new [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
 - `redirect_uri` - A list of URIs to which the [**Authorization Server**](/docs/oauth/introduction#authorization-server) will send the user-agent (browser) after completing the authorization step. These can be deep links to mobile or desktop apps as well, but they must be exact URLs, without wildcards.
+- `scope` -  A space separated string of scopes that the [**Client**](/docs/oauth/introduction#client) will request access to.
+    - `offline_access`: You need to include this scope if you want to use the [**OAuth2 Refresh Token**](/docs/oauth/introduction#oauth2-refresh-token) to get a new [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
+
 
 If the creation was successful, the API will return a response that looks like this:
 
@@ -107,8 +111,6 @@ If the creation was successful, the API will return a response that looks like t
     "client_secret": "<CLIENT_SECRET>",
     "callback_urls": ["https://<YOUR_APPLICATION_DOMAIN>/oauth/callback"],
 }
-
-
 ```
 
 Based on the client creation process we can also infer two additional values that we will need later on:
@@ -122,6 +124,26 @@ In the next steps we will use the values to complete several configurations.
 
 :::
 
+### Change the default token lifespan
+
+By default, the tokens used in the authorization flow will have the following lifespans:
+  - [OAuth2 Access Token](/docs/oauth/introduction#oauth2-access-token): 1 hour
+  - [OAuth2 ID Token](/docs/oauth/introduction#oauth2-id-token): 1 hour
+  - [OAuth2 Refresh Token](/docs/oauth/introduction#oauth2-refresh-token): 30 days
+
+If you want to change the default values you need to specify additional properties in the [**Client**](/docs/oauth/introduction#client) creation request body.
+Use string values that signify time duration in milliecoseconds, seconds, minutes or hours (e.g. `"2000ms"`, `"60s"`, `"30m"`, `"1h"`).
+
+- **OAuth2 Access Token** - Set the `authorization_code_grant_access_token_lifespan` property.
+- **OAuth2 ID Token** - Set the `authorization_code_grant_id_token_lifespan` property.
+- **OAuth2 Refresh Token** - Set both the `authorization_code_grant_refresh_token_lifespan` and the `refresh_token_grant_refresh_token_lifespan` properties to the same value.
+
+### Usage Without Refresh Tokens
+
+If your use case involves a long lasting session that cannot accomodate the process of changing the [**OAuth2 Refresh Token**](/docs/oauth/introduction#oauth2-refresh-token) when it expires, you can adjust the [**Client**](/docs/oauth/introduction#client) that you are creating. 
+In order to do this you need to:
+  - Omit the `offline_access` scope from the **Client** creation request body. This way we are making sure that we avoid the use of **OAuth2 Refresh Tokens** in our authorization flow.
+  - Set the `authorization_code_grant_access_token_lifespan` property to a high value. You will be allowed to use the token without reauthenticating for a really long time. 
 
 ## 3. Set Up your Authorization Service 
 
@@ -335,6 +357,13 @@ The configuration parameters can be determined based on the response that we rec
 
 </OAuthFrontendTabs>
 
+:::info
+
+If you want to use the [**OAuth2 Refresh Tokens**](/docs/oauth/introduction#oauth2-refresh-token) make sure to include the `offline_access` scope during the initialization step.
+
+:::
+
+
 ### 4. Complete the final token exchange
 
 After you have obtained the **OAuth2 Access Token** you will have to exchange it for a **SuperTokens Session Access Token**.

v2/oauth/multiple-frontends-with-separate-backends.mdx

@@ -87,6 +87,7 @@ curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
       "client_name": "<YOUR_CLIENT_NAME>",
       "response_types": ["code", "id_token"],
       "grant_types": ["authorization_code", "refresh_token"],
+      "scope": "offline_access <custom_scope_1> <custom_scope_2>",
       "redirect_uri": ["https://<YOUR_APPLICATION_DOMAIN>/oauth/callback"]
     }'
 ```
@@ -100,6 +101,8 @@ curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
     - `authorization_code`: Allows exchanging the **Authorization Code** for an [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
     - `refresh_token`: Allows exchanging the [**OAuth2 Refresh Token**](/docs/oauth/introduction#oauth2-refresh-token) for a new [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
 - `redirect_uri` - A list of URIs to which the [**Authorization Server**](/docs/oauth/introduction#authorization-server) will send the user-agent (browser) after completing the authorization step. These can be deep links to mobile or desktop apps as well, but they must be exact URLs, without wildcards.
+- `scope` -  A space separated string of scopes that the [**Client**](/docs/oauth/introduction#client) will request access to.
+    - `offline_access`: You need to include this scope if you want to use the [**OAuth2 Refresh Token**](/docs/oauth/introduction#oauth2-refresh-token) to get a new [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
 
 If the creation was successful, the API will return a response that looks like this:
 
@@ -126,6 +129,26 @@ In the next steps we will use the values to complete several configurations.
 
 :::
 
+### Change the default token lifespan
+
+By default, the tokens used in the authorization flow will have the following lifespans:
+  - [OAuth2 Access Token](/docs/oauth/introduction#oauth2-access-token): 1 hour
+  - [OAuth2 ID Token](/docs/oauth/introduction#oauth2-id-token): 1 hour
+  - [OAuth2 Refresh Token](/docs/oauth/introduction#oauth2-refresh-token): 30 days
+
+If you want to change the default values you need to specify additional properties in the [**Client**](/docs/oauth/introduction#client) creation request body.
+Use string values that signify time duration in milliecoseconds, seconds, minutes or hours (e.g. `"2000ms"`, `"60s"`, `"30m"`, `"1h"`).
+
+- **OAuth2 Access Token** - Set the `authorization_code_grant_access_token_lifespan` property.
+- **OAuth2 ID Token** - Set the `authorization_code_grant_id_token_lifespan` property.
+- **OAuth2 Refresh Token** - Set both the `authorization_code_grant_refresh_token_lifespan` and the `refresh_token_grant_refresh_token_lifespan` properties to the same value.
+
+### Usage Without Refresh Tokens
+
+If your use case involves a long lasting session that cannot accomodate the process of changing the [**OAuth2 Refresh Token**](/docs/oauth/introduction#oauth2-refresh-token) when it expires, you can adjust the [**Client**](/docs/oauth/introduction#client) that you are creating. 
+In order to do this you need to:
+  - Omit the `offline_access` scope from the **Client** creation request body. This way we are making sure that we avoid the use of **OAuth2 Refresh Tokens** in our authorization flow.
+  - Set the `authorization_code_grant_access_token_lifespan` property to a high value. You will be allowed to use the token without reauthenticating for a really long time. 
 
 
 ## 3. Set Up your Authorization Service 
@@ -386,6 +409,11 @@ This way the user will end up accessing the actual login page served by the **Au
 
 </OAuthBackendTabs>
 
+:::info
+
+If you want to use the [**OAuth2 Refresh Tokens**](/docs/oauth/introduction#oauth2-refresh-token) make sure to include the `offline_access` scope during the initialization step.
+
+:::
 
 ## 5. Update the login flow in your frontend applications
 

v2/oauth/reuse-website-login.mdx

@@ -81,6 +81,7 @@ curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
       "response_types": ["code", "id_token"],
       "grant_types": ["authorization_code", "refresh_token"],
       "tokenEndpointAuthMethod": "none",
+      "scope": "offline_access <custom_scope_1> <custom_scope_2>",
       "redirect_uri": ["https://<YOUR_APPLICATION_DOMAIN>/oauth/callback"]
     }'
 ```
@@ -93,6 +94,8 @@ curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
     - `authorization_code`: Allows exchanging the **Authorization Code** for an [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
     - `refresh_token`: Allows exchanging the [**OAuth2 Refresh Token**](/docs/oauth/introduction#oauth2-refresh-token) for a new [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
 - `redirect_uri` - A list of URIs to which the [**Authorization Server**](/docs/oauth/introduction#authorization-server) will send the user-agent (browser) after completing the authorization step. These can be deep links to mobile or desktop apps as well, but they must be exact URLs, without wildcards.
+- `scope` -  A space separated string of scopes that the [**Client**](/docs/oauth/introduction#client) will request access to.
+    - `offline_access`: You need to include this scope if you want to use the [**OAuth2 Refresh Token**](/docs/oauth/introduction#oauth2-refresh-token) to get a new [**OAuth2 Access Token**](/docs/oauth/introduction#oauth2-access-token).
 
 If the creation was successful, the API will return a response that looks like this:
 
@@ -117,6 +120,20 @@ In the next steps we will use the values to complete several configurations.
 
 :::
 
+### Change the default token lifespan
+
+By default, the tokens used in the authorization flow will have the following lifespans:
+  - [OAuth2 Access Token](/docs/oauth/introduction#oauth2-access-token): 1 hour
+  - [OAuth2 ID Token](/docs/oauth/introduction#oauth2-id-token): 1 hour
+  - [OAuth2 Refresh Token](/docs/oauth/introduction#oauth2-refresh-token): 30 days
+
+If you want to change the default values you need to specify additional properties in the [**Client**](/docs/oauth/introduction#client) creation request body.
+Use string values that signify time duration in milliecoseconds, seconds, minutes or hours (e.g. `"2000ms"`, `"60s"`, `"30m"`, `"1h"`).
+
+- **OAuth2 Access Token** - Set the `authorization_code_grant_access_token_lifespan` property.
+- **OAuth2 ID Token** - Set the `authorization_code_grant_id_token_lifespan` property.
+- **OAuth2 Refresh Token** - Set both the `authorization_code_grant_refresh_token_lifespan` and the `refresh_token_grant_refresh_token_lifespan` properties to the same value.
+
 ## 3. Make sure that you have properly configured the Authorization Service
 
 If you have not set up the [**Authorization Service**](/docs/oauth/introduction#authorization-service) yet, please check one of the previous guides based whether you use multiple backend service:
@@ -193,6 +210,12 @@ The configuration parameters can be determined based on the response that we rec
 
 </OAuthMobileTabs>
 
+:::info
+
+If you want to use the [**OAuth2 Refresh Tokens**](/docs/oauth/introduction#oauth2-refresh-token) make sure to include the `offline_access` scope during the initialization step.
+
+:::
+
 
 ## 5. Test the new authentication flow