From 8970d5fe5741147938975bfc41ca7c8bc0bfb10a Mon Sep 17 00:00:00 2001 From: Isaakske Date: Fri, 14 Aug 2026 16:23:23 +0200 Subject: [PATCH 1/2] add refresh tokens section --- .../includes/23_authentication_scopes.html.md | 2 ++ .../24_authentication_refresh_tokens.html.md | 20 +++++++++++++++++++ source/index.html.md | 1 + 3 files changed, 23 insertions(+) create mode 100644 source/includes/24_authentication_refresh_tokens.html.md diff --git a/source/includes/23_authentication_scopes.html.md b/source/includes/23_authentication_scopes.html.md index 5cd4f3d8009..4343ee93a59 100644 --- a/source/includes/23_authentication_scopes.html.md +++ b/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,7 @@ 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). ### Claims diff --git a/source/includes/24_authentication_refresh_tokens.html.md b/source/includes/24_authentication_refresh_tokens.html.md new file mode 100644 index 00000000000..8f2da7c1208 --- /dev/null +++ b/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=" \ + -d "client_secret=" \ + -d "grant_type=refresh_token" \ + -d "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. diff --git a/source/index.html.md b/source/index.html.md index 3bd2ba6d651..39e25cf1df6 100644 --- a/source/index.html.md +++ b/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 From c6deba6de81f733bcdeae83ab85010217dad8643 Mon Sep 17 00:00:00 2001 From: Isaakske Date: Mon, 17 Aug 2026 12:49:45 +0200 Subject: [PATCH 2/2] add deprecation warning --- source/includes/23_authentication_scopes.html.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/includes/23_authentication_scopes.html.md b/source/includes/23_authentication_scopes.html.md index 4343ee93a59..8b0ceb313bc 100644 --- a/source/includes/23_authentication_scopes.html.md +++ b/source/includes/23_authentication_scopes.html.md @@ -39,6 +39,11 @@ 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). + + ### Claims OpenID Connect specifies a set of standard claims.