From 6d816939ffe48fa76a03274d044d5442e7bf8eab Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 30 Jul 2026 10:47:05 +0100 Subject: [PATCH 1/3] Add cross-references between the OpenID endpoints of the Client-Server API, Server-Server API and Identity-Service API --- changelogs/client_server/newsfragments/2426.clarification | 1 + .../identity_service/newsfragments/2426.clarification | 1 + changelogs/server_server/newsfragments/2426.clarification | 1 + content/client-server-api/modules/openid.md | 3 ++- content/identity-service-api.md | 4 ++++ content/server-server-api.md | 7 ++++--- data/api/client-server/definitions/openid_token.yaml | 3 ++- data/api/client-server/openid.yaml | 4 ++-- data/api/identity/v2_auth.yaml | 4 +++- data/api/server-server/openid.yaml | 4 ++++ 10 files changed, 24 insertions(+), 8 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2426.clarification create mode 100644 changelogs/identity_service/newsfragments/2426.clarification create mode 100644 changelogs/server_server/newsfragments/2426.clarification diff --git a/changelogs/client_server/newsfragments/2426.clarification b/changelogs/client_server/newsfragments/2426.clarification new file mode 100644 index 000000000..a3cd64107 --- /dev/null +++ b/changelogs/client_server/newsfragments/2426.clarification @@ -0,0 +1 @@ +Add cross-references between the OpenID endpoints of the Client-Server API, Server-Server API and Identity-Service API. diff --git a/changelogs/identity_service/newsfragments/2426.clarification b/changelogs/identity_service/newsfragments/2426.clarification new file mode 100644 index 000000000..a3cd64107 --- /dev/null +++ b/changelogs/identity_service/newsfragments/2426.clarification @@ -0,0 +1 @@ +Add cross-references between the OpenID endpoints of the Client-Server API, Server-Server API and Identity-Service API. diff --git a/changelogs/server_server/newsfragments/2426.clarification b/changelogs/server_server/newsfragments/2426.clarification new file mode 100644 index 000000000..a3cd64107 --- /dev/null +++ b/changelogs/server_server/newsfragments/2426.clarification @@ -0,0 +1 @@ +Add cross-references between the OpenID endpoints of the Client-Server API, Server-Server API and Identity-Service API. diff --git a/content/client-server-api/modules/openid.md b/content/client-server-api/modules/openid.md index 1aff30cd6..4a1f63461 100644 --- a/content/client-server-api/modules/openid.md +++ b/content/client-server-api/modules/openid.md @@ -4,6 +4,7 @@ This module allows users to verify their identity with a third-party service. The third-party service does need to be matrix-aware in that it will need to know to resolve matrix homeservers to exchange the user's -token for identity information. +token for identity information, using the [OpenID section of the +Server-Server API](/server-server-api/#openid). {{% http-api spec="client-server" api="openid" %}} diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 50e4847f0..1933db6cf 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -164,6 +164,10 @@ of access tokens to authenticate users. The access tokens provided by an Identity Server cannot be used to authenticate Client-Server API requests. +An Identity Server access token is obtained by exchanging an OpenID +token, which the user's client requests from their homeserver using the +Client-Server API's [OpenID module](/client-server-api/#openid). + Access tokens may be provided via a request header, using the Authentication Bearer scheme: `Authorization: Bearer TheTokenHere`. diff --git a/content/server-server-api.md b/content/server-server-api.md index c29ad0e82..79afe748d 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -1134,9 +1134,10 @@ more specific queries that can be made. ## OpenID Third-party services can exchange an access token previously generated -by the Client-Server API for information -about a user. This can help verify that a user is who they say they are -without granting full access to the user's account. +by the [OpenID module of the Client-Server +API](/client-server-api/#openid) for information about a user. This can +help verify that a user is who they say they are without granting full +access to the user's account. Access tokens generated by the OpenID API are only good for the OpenID API and nothing else. diff --git a/data/api/client-server/definitions/openid_token.yaml b/data/api/client-server/definitions/openid_token.yaml index e74ddfff5..5cd5c67ef 100644 --- a/data/api/client-server/definitions/openid_token.yaml +++ b/data/api/client-server/definitions/openid_token.yaml @@ -20,7 +20,8 @@ properties: description: |- An access token the consumer may use to verify the identity of the person who generated the token. This is given to the federation - API `GET /openid/userinfo` to verify the user's identity. + API [`GET /_matrix/federation/v1/openid/userinfo`](/server-server-api/#get_matrixfederationv1openiduserinfo) + to verify the user's identity. token_type: type: string description: The string `Bearer`. diff --git a/data/api/client-server/openid.yaml b/data/api/client-server/openid.yaml index 9307c52be..aa7a65b00 100644 --- a/data/api/client-server/openid.yaml +++ b/data/api/client-server/openid.yaml @@ -22,8 +22,8 @@ paths: description: |- Gets an OpenID token object that the requester may supply to another service to verify their identity in Matrix. The generated token is only - valid for exchanging for user information from the federation API for - OpenID. + valid for exchanging for user information from the + [federation API for OpenID](/server-server-api/#get_matrixfederationv1openiduserinfo). The access token generated is only valid for the OpenID API. It cannot be used to request another OpenID access token or call `/sync`, for diff --git a/data/api/identity/v2_auth.yaml b/data/api/identity/v2_auth.yaml index 3811768c8..75e03f0cb 100644 --- a/data/api/identity/v2_auth.yaml +++ b/data/api/identity/v2_auth.yaml @@ -22,7 +22,9 @@ paths: description: |- Exchanges an OpenID token from the homeserver for an access token to access the identity server. The request body is the same as the values - returned by `/openid/request_token` in the Client-Server API. + returned by + [`POST /_matrix/client/v3/user/{userId}/openid/request_token`](/client-server-api/#post_matrixclientv3useruseridopenidrequest_token) + in the Client-Server API. operationId: registerAccount requestBody: content: diff --git a/data/api/server-server/openid.yaml b/data/api/server-server/openid.yaml index 22b7f9411..cfca9c956 100644 --- a/data/api/server-server/openid.yaml +++ b/data/api/server-server/openid.yaml @@ -24,6 +24,10 @@ paths: Exchanges an OpenID access token for information about the user who generated the token. Currently this only exposes the Matrix User ID of the owner. + + The access token is obtained by the Client-Server API's + [`POST /_matrix/client/v3/user/{userId}/openid/request_token`](/client-server-api/#post_matrixclientv3useruseridopenidrequest_token) + endpoint. operationId: exchangeOpenIdToken parameters: - in: query From ccb4c8d319f8d1466e386a100e17c017232f00e8 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 11 Aug 2026 16:38:45 +0100 Subject: [PATCH 2/3] Apply suggestion from @richvdh --- content/identity-service-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 1933db6cf..e4046513b 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -164,7 +164,7 @@ of access tokens to authenticate users. The access tokens provided by an Identity Server cannot be used to authenticate Client-Server API requests. -An Identity Server access token is obtained by exchanging an OpenID +An Identity Service access token is obtained by exchanging an OpenID token, which the user's client requests from their homeserver using the Client-Server API's [OpenID module](/client-server-api/#openid). From 109babaa657c565e0bca2cc97621fad760809884 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 11 Aug 2026 16:45:29 +0100 Subject: [PATCH 3/3] Apply suggestion from @richvdh --- content/identity-service-api.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/content/identity-service-api.md b/content/identity-service-api.md index e4046513b..1e3bb77f6 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -164,9 +164,11 @@ of access tokens to authenticate users. The access tokens provided by an Identity Server cannot be used to authenticate Client-Server API requests. -An Identity Service access token is obtained by exchanging an OpenID -token, which the user's client requests from their homeserver using the -Client-Server API's [OpenID module](/client-server-api/#openid). +An Identity Service access token may be obtained as follows: + 1. The user's client requests an OpenID token from the homeserver using the + Client-Server API's [OpenID module](/client-server-api/#openid). + 2. The OpenID token is exchanged for an Identity Service access token via the + [`POST /_matrix/identity/v2/account/register`](#post_matrixidentityv2accountregister) endpoint. Access tokens may be provided via a request header, using the Authentication Bearer scheme: `Authorization: Bearer TheTokenHere`.