From 3bd7498bc764c5810ba0881e281f22479c4c2ab4 Mon Sep 17 00:00:00 2001
From: rusirijayodaillesinghe <rusiri@wso2.com>
Date: Fri, 1 Nov 2024 11:04:55 +0530
Subject: [PATCH] Add multiple-active-access-tokens documentation. Fixes
 https://github.com/wso2/docs-apim/issues/8376 for APIM 4.0.0

---
 .../oauth2/multiple-active-access-tokens.md   | 43 +++++++++++++++++++
 en/mkdocs.yml                                 |  2 +
 2 files changed, 45 insertions(+)
 create mode 100644 en/docs/design/api-security/oauth2/multiple-active-access-tokens.md

diff --git a/en/docs/design/api-security/oauth2/multiple-active-access-tokens.md b/en/docs/design/api-security/oauth2/multiple-active-access-tokens.md
new file mode 100644
index 0000000000..d079462414
--- /dev/null
+++ b/en/docs/design/api-security/oauth2/multiple-active-access-tokens.md
@@ -0,0 +1,43 @@
+# Multiple Active Access Tokens
+
+WSO2 API Manager by default allows only one active access token to be in existence for the same Consumer Key, User and Scope combination at a given time. This behaviour can be modified to allow multiple access tokens as described in the following sections.
+
+## JWT
+
+When issuing `JWT` tokens before the expiry or revocation of the previous token, the default behaviour is to revoke the previous token and issue a new token. With the following configuration, it can be configured to issue a new token before expiry and without revoking the old token, allowing the existence of multiple active access tokens at the same time.
+
+```toml
+[oauth.jwt.renew_token_without_revoking_existing]
+enable = true
+```
+
+By default only the `client_credentials` grant type is allowed to generate multiple access tokens. This can be configured by the following configuration.
+
+```toml
+[oauth.jwt.renew_token_without_revoking_existing]
+enable = true
+allowed_grant_types = [“client_credentials”, “password”]
+```
+
+!!! note
+    If you are customizing the `allowed_grant_types` make sure to add or remove the default value `client_credentials` as per the requirement.
+
+## Opaque
+
+When issuing `opaque` tokens before the expiry or revocation of the previous token, the default behaviour is to issue the existing token which is stored in the DB. With the following configuration, it can be configured to allow the existence of multiple active access tokens at the same time.
+
+```toml
+[oauth.opaque.renew_token_without_revoking_existing]
+enable = true
+```
+
+By default only the `client_credentials` grant type is allowed to generate multiple access tokens. This can be configured by the following configuration.
+
+```toml
+[oauth.opaque.renew_token_without_revoking_existing]
+enable = true
+allowed_grant_types = [“client_credentials”, “password”]
+```
+
+!!! note
+    If you are customizing the `allowed_grant_types` make sure to add or remove the default value `client_credentials` as per the requirement.
diff --git a/en/mkdocs.yml b/en/mkdocs.yml
index be8621c48d..a09dab6b86 100644
--- a/en/mkdocs.yml
+++ b/en/mkdocs.yml
@@ -148,6 +148,7 @@ nav:
                 - Token Persistence: design/api-security/oauth2/token-persistence.md
                 - Encrypt OAuth2 Tokens: design/api-security/oauth2/encrypting-oauth2-tokens.md
                 - Hashing OAuth Keys: design/api-security/oauth2/hashing-oauth-keys.md
+                - Multiple Active Access Tokens: design/api-security/oauth2/multiple-active-access-tokens.md
                 - Provision Out-of-Band OAuth Clients: design/api-security/oauth2/provisioning-out-of-band-oauth-clients.md
                 - Secure OAuth Token with HMAC Validation: design/api-security/oauth2/securing-oauth-token-with-hmac-validation.md
             - Threat Protection:
@@ -1909,6 +1910,7 @@ plugins:
               'learn/api-security/oauth2/token-persistence.md': 'https://apim.docs.wso2.com/en/4.0.0/design/api-security/oauth2/token-persistence/'
               'learn/api-security/oauth2/encrypting-oauth2-tokens.md': 'https://apim.docs.wso2.com/en/4.0.0/design/api-security/oauth2/encrypting-oauth2-tokens/'
               'learn/api-security/oauth2/hashing-oauth-keys.md': 'https://apim.docs.wso2.com/en/4.0.0/design/api-security/oauth2/hashing-oauth-keys/'
+              'learn/api-security/oauth2/multiple-active-access-tokens.md': 'https://apim.docs.wso2.com/en/4.0.0/design/api-security/oauth2/multiple-active-access-tokens/'
               'learn/api-security/oauth2/provisioning-out-of-band-oauth-clients.md': 'https://apim.docs.wso2.com/en/4.0.0/design/api-security/oauth2/provisioning-out-of-band-oauth-clients/'
               'learn/api-security/oauth2/securing-oauth-token-with-hmac-validation.md': 'https://apim.docs.wso2.com/en/4.0.0/design/api-security/oauth2/securing-oauth-token-with-hmac-validation/'
               'learn/api-security/threat-protection/bot-detection.md': 'https://apim.docs.wso2.com/en/4.0.0/design/api-security/threat-protection/bot-detection/'