Adding documentation to reuse access tokens

Author: theManikJindal

src/pages/guides/authentication/ServerToServerAuthentication/IMS.md

@@ -2,6 +2,13 @@
 
 Following is an API reference for Adobe Identity Management Services (IMS) APIs.
 
+- [Fetching access tokens](#fetching-access-tokens)
+- [Refreshing access tokens](#refreshing-access-tokens)
+- [List all client secrets](#list-all-client-secrets)
+- [Add client secret to credential](#add-client-secret-to-credential)
+- [Remove client secret from credential](#remove-client-secret-from-credential)
+
+
 ## Fetching access tokens
 
 The OAuth Server-to-server credential uses the `client_credentials` grant to generate access tokens.

src/pages/guides/authentication/ServerToServerAuthentication/implementation.md

@@ -5,7 +5,8 @@ The following guide goes over finer implementation details for OAuth Server-to-S
 
 On this page:
 + [Setting up the OAuth Server-to-Server credential](#setting-up-the-oauth-server-to-server-credential)
-+ [Generating access tokens using cURL](#generating-access-tokens-using-curl)
++ [Generate access tokens](#generate-access-tokens)
++ [Generating access tokens programmatically](#generating-access-tokens-programmatically)
 + [Generating access tokens using standard OAuth2 libraries](#generating-access-tokens-using-standard-oauth2-libraries)
 + [Rotating client secrets](#rotating-client-secrets)
 + [Rotating client secrets programmatically](#rotating-client-secrets-programmatically)
@@ -37,13 +38,21 @@ The product profile selection works the same way as it does for Service Account
 
 Generating access tokens for experimentation with the OAuth Server-to-Server credential is straightforward. You can use the 'Generate access token' button on the credential overview page or copy the cURL command and use the command line to generate an access token for quick use.
 
+![](../../../images/oauth-server-to-server-credential-generate-access-tokens.png)
+
+### Generating access tokens programmatically
+
+See this cURL request to understand how your integration or application can generate access tokens programmatically. 
+
 ```curl
 curl -X POST 'https://ims-na1.adobelogin.com/ims/token/v3' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -d 'client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&grant_type=client_credentials&scope={SCOPES}'
 ```
 
-![](../../../images/oauth-server-to-server-credential-generate-access-tokens.png)
+Your integration can generate access tokens when needed. However, it is a good practice to cache access tokens for reuse until they expire. Integrations should avoid generating a new access token when a previously generated access token has not expired and can be reused. Adobe can throttle your integration if it generates too many access tokens.
+
+Access tokens usually expire in 24 hours. To check the expiry time of an access token, see the `expires_in` field in the API response returned by the above cURL request. Note: The `expires_in` time is in seconds. See [API reference](./IMS.md#fetching-access-tokens).
 
 ### Generating access tokens using standard OAuth2 libraries
 
@@ -96,42 +105,42 @@ Follow the steps below to rotate client secrets programmatically for the OAuth S
 1. Add I/O Management API to your project: This API allows your credential to read, add, and delete its client secrets.
 
 2. Go to the OAuth Server-to-Server credential overview page and grab the URL. For example - 
-```
-https://developer.adobe.com/console/projects/23294/4566206088344958295/credentials/436084/details/oauthservertoserver
-```
+     ```
+     https://developer.adobe.com/console/projects/23294/4566206088344958295/credentials/436084/details/oauthservertoserver
+     ```
 
 3. Grab the value of `org id` and `credential id` from the URL by comparing it to the templated URL below.
-```
-https://developer.adobe.com/console/projects/{orgId}/{projectId}/credentials/{credentialId}/details/oauthservertoserver
-```
+     ```
+     https://developer.adobe.com/console/projects/{orgId}/{projectId}/credentials/{credentialId}/details/oauthservertoserver
+     ```
 
 4. Construct the secrets request endpoint by substituting the value of `org id` and `credential id` in the URL below. 
-```
-https://api.adobe.io/console/organizations/{orgId}/credentials/{credentialId}/secrets
-```
-```
-https://api.adobe.io/console/organizations/23294/credentials/436084/secrets
-```
+     ```
+     https://api.adobe.io/console/organizations/{orgId}/credentials/{credentialId}/secrets
+     ```
+     ```
+     https://api.adobe.io/console/organizations/23294/credentials/436084/secrets
+     ```
 
 5. Generate an access token using the existing client secret (see the section on [generating access tokens](#generate-access-tokens)).  Make sure to include scopes that the I/O Management API requires: 
 
-```AdobeID, openid, read_organizations, additional_info.projectedProductContext, additional_info.roles, adobeio_api, read_client_secret, manage_client_secrets```
+     ```AdobeID, openid, read_organizations, additional_info.projectedProductContext, additional_info.roles, adobeio_api, read_client_secret, manage_client_secrets```
 
 6. Call the API to list all existing client secrets. Note: you can grab your `client_id` from the OAuth Server-to-Server credential overview page. 
 
-```curl
-curl -X GET 'https://api.adobe.io/console/organizations/{orgId}/credentials/{credentialId}/secrets' \
-     -H 'Authorization: Bearer {ACCESS TOKEN GENERATED IN STEP 5}'
-     -H 'x-api-key: {CLIENT ID FROM STEP 6}'
-```
+     ```curl
+     curl -X GET 'https://api.adobe.io/console/organizations/{orgId}/credentials/{credentialId}/secrets' \
+          -H 'Authorization: Bearer {ACCESS TOKEN GENERATED IN STEP 5}'
+          -H 'x-api-key: {CLIENT ID FROM STEP 6}'
+     ```
 
-1.  Call the API to add another client secret to your credential. The API response contains the `client_secret` that was added and its `uuid`. This `client_secret` will never be returned in plain text by any other API response. However, you can still find it on the Developer Console UI.
+7.  Call the API to add another client secret to your credential. The API response contains the `client_secret` that was added and its `uuid`. This `client_secret` will never be returned in plain text by any other API response. However, you can still find it on the Developer Console UI.
 
-```curl
-curl -X POST 'https://api.adobe.io/console/organizations/{orgId}/credentials/{credentialId}/secrets' \
-     -H 'Authorization: Bearer {ACCESS TOKEN GENERATED IN STEP 5}'
-     -H 'x-api-key: {CLIENT ID FROM STEP 6}'
-```
+     ```curl
+     curl -X POST 'https://api.adobe.io/console/organizations/{orgId}/credentials/{credentialId}/secrets' \
+          -H 'Authorization: Bearer {ACCESS TOKEN GENERATED IN STEP 5}'
+          -H 'x-api-key: {CLIENT ID FROM STEP 6}'
+     ```
 
 8.  Update your application to use the new client secret. 
 
@@ -140,8 +149,8 @@ curl -X POST 'https://api.adobe.io/console/organizations/{orgId}/credentials/{cr
 10. Call the API to delete the old client secret from your credential by passing the `uuid` in the URL
 
 
-```curl
-curl -X DELETE 'https://api.adobe.io/console/organizations/{orgId}/credentials/{credentialId}/secrets/{uuid from step 9}' \
-     -H 'Authorization: Bearer {ACCESS TOKEN GENERATED IN STEP 5}'
-     -H 'x-api-key: {CLIENT ID FROM STEP 6}'
-```
+     ```curl
+     curl -X DELETE 'https://api.adobe.io/console/organizations/{orgId}/credentials/{credentialId}/secrets/{uuid from step 9}' \
+          -H 'Authorization: Bearer {ACCESS TOKEN GENERATED IN STEP 5}'
+          -H 'x-api-key: {CLIENT ID FROM STEP 6}'
+     ```