[CLEARFACTS-13143] add refresh tokens section

source/includes/23_authentication_scopes.html.md

@@ -18,6 +18,7 @@ This is a list of all the supported scopes in our API:
 Scope                  | Type   | Description
 -----------------------|--------|------------------------
 `openid`               | OpenID | This is a technical scope, it should always be requested when using the OpenID Connect flow, it also allows access to a unique identification of the user (the `sub` claim)
+`offline_access`       | OpenID | Requests a refresh token and a short-lived access token so the application can retain access after the user leaves
 `email`                | OpenID | Access to a users emailaddress (via the ``/userinfo`` endpoint)
 `profile`              | OpenID | Access to a users name, locale
 `accountant`           | API    | Consult the details of the accountant
@@ -36,6 +37,12 @@ Each token, be it a personal access token or a token acquired through OpenID Con
 should have been granted one or more scopes for it to be of any use.
 
 If you are using OpenID Connect, you are required to request the `openid` scope.
+Request the `offline_access` scope if your application needs continued access through [refresh tokens](#refresh-tokens).
+
+<aside class="warning">
+Not passing the `offline_access` scope is deprecated.
+See <a href="#refresh-tokens">refresh tokens</a>.
+</aside>
 
 ### Claims
 

source/includes/24_authentication_refresh_tokens.html.md

@@ -0,0 +1,20 @@
+## Refresh Tokens
+
+We are gradually migrating OpenID Connect integrations from long-lived access tokens to short-lived access tokens combined with refresh tokens.
+
+To opt in, include the `offline_access` scope in the authorization request. When the authorization code is exchanged at the token endpoint, the response contains an access token that is valid for one hour and a refresh token that is valid for 30 days.
+
+When the access token expires, request a new token pair by sending the refresh token to the token endpoint:
+
+```shell
+curl -X POST \
+  https://api.clearfacts.be/oauth2-server/token \
+  -d "client_id=<client-id>" \
+  -d "client_secret=<client-secret>" \
+  -d "grant_type=refresh_token" \
+  -d "refresh_token=<refresh-token>"
+```
+
+The response contains a new one-hour access token and a new refresh token. Replace the previous refresh token with the new one and store it securely. Repeat this flow whenever the current access token expires. If the refresh token expires or is revoked, the user must complete the authorization flow again.
+
+We will contact all existing integrators as this migration progresses. In a timeframe that has not yet been determined, we will stop supporting long-lived access tokens issued through OpenID Connect. Manually created [personal access tokens](#personal-access-token), which do not expire, are not affected.

source/index.html.md

@@ -18,6 +18,7 @@ includes:
   - 21_authentication_personal_access_token.html.md
   - 22_authentication_oidc.html.md
   - 23_authentication_scopes.html.md
+  - 24_authentication_refresh_tokens.html.md
   - 30_0_0_recipes.html.md
   - 30_1_1_accountant.html.md
   - 30_1_2_associates.html.md