Merge branch 'dblessing_oauth_documentation' into 'master'

Update documentation for expiring OAuth2 access tokens

See merge request gitlab-org/gitlab!70710

doc/api/oauth2.md

@@ -412,6 +412,16 @@ prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doo
 
 Don't rely on these fields as they are slated for removal in a later release.
 
+## Revoke a token
+
+To revoke a token, use the `revoke` endpoint. The API returns a 200 response code and an empty
+JSON hash to indicate success. 
+
+```ruby
+parameters = 'client_id=APP_ID&client_secret=APP_SECRET&token=TOKEN'
+RestClient.post 'https://gitlab.example.com/oauth/revoke', parameters
+```
+
 ## OAuth 2.0 tokens and GitLab registries
 
 Standard OAuth 2.0 tokens support different degrees of access to GitLab

doc/integration/oauth_provider.md

@@ -88,6 +88,25 @@ To create an application for your GitLab instance:
 When creating application in the **Admin Area** , you can mark it as _trusted_.
 The user authorization step is automatically skipped for this application.
 
+## Expiring Access Tokens
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21745) in GitLab 14.3.
+
+By default, all new applications expire access tokens after 2 hours. In GitLab 14.2 and
+earlier, OAuth access tokens had no expiration.
+
+All integrations should update to support access token refresh.
+
+When creating new applications, you can opt-out of expiry for backward compatibility by clearing
+**Expire access tokens** when creating them. The ability to opt-out
+[is deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/340848).
+
+Existing:
+
+- Applications can have expiring access tokens. Edit the application and select
+  **Expire access tokens** to enable them. 
+- Tokens must be [revoked](../api/oauth2.md#revoke-a-token) or they don't expire.
+
 ## Authorized applications
 
 Every application you authorize with your GitLab credentials is shown