Merge branch 'dblessing_oauth_doc_refresh_tokens' into 'master'

Add OAuth Refresh Token documentation

See merge request gitlab-org/gitlab!68007

doc/api/index.md

@@ -167,7 +167,11 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/ap
 Read more about [GitLab as an OAuth2 provider](oauth2.md).
 
 NOTE:
-We recommend that OAuth access tokens have an expiration. You can use a `refresh_token` to refresh tokens. Integrations may need to be updated to refresh tokens prior to expiration, which is based on the [expires_in](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14) property in the token endpoint response.  
+We recommend OAuth access tokens have an expiration. You can use the `refresh_token` parameter
+to refresh tokens. Integrations may need to be updated to use refresh tokens prior to
+expiration, which is based on the [expires_in](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14)
+property in the token endpoint response. See [OAuth2 token](oauth2.md) documentation
+for examples requesting a new access token using a refresh token.
 
 A default refresh setting of two hours is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336598).
 

doc/api/oauth2.md

@@ -124,6 +124,28 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD
    }
    ```
    
+1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may
+   be used even after the `access_token` itself expires. This request:
+   - Invalidates the existing `access_token` and `refresh_token`.
+   - Sends new tokens in the response.
+
+   ```ruby
+     parameters = 'client_id=APP_ID&client_secret=APP_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER'
+     RestClient.post 'https://gitlab.example.com/oauth/token', parameters
+   ```
+
+   Example response:
+    
+   ```json
+   {
+     "access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68",
+     "token_type": "bearer",
+     "expires_in": 7200,
+     "refresh_token": "803c1fd487fec35562c205dac93e9d8e08f9d3652a24079d704df3039df1158f",
+     "created_at": 1628711391
+   }
+   ```
+
 NOTE:
 The `redirect_uri` must match the `redirect_uri` used in the original
 authorization request.
@@ -182,6 +204,28 @@ be used as a CSRF token.
    }
    ```
    
+1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may
+   be used even after the `access_token` itself expires. This request:
+   - Invalidates the existing `access_token` and `refresh_token`.
+   - Sends new tokens in the response.
+
+   ```ruby
+     parameters = 'client_id=APP_ID&client_secret=APP_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI'
+     RestClient.post 'https://gitlab.example.com/oauth/token', parameters
+   ```
+
+   Example response:
+
+   ```json
+   {
+     "access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68",
+     "token_type": "bearer",
+     "expires_in": 7200,
+     "refresh_token": "803c1fd487fec35562c205dac93e9d8e08f9d3652a24079d704df3039df1158f",
+     "created_at": 1628711391
+   }
+   ```
+
 NOTE:
 The `redirect_uri` must match the `redirect_uri` used in the original
 authorization request.