--- title: "Process UserInfo Request" method: POST path: "/api/{serviceId}/auth/userinfo" tags: ["UserInfo Endpoint"] --- # Process UserInfo Request `POST /api/{serviceId}/auth/userinfo` This API gathers information about a user. ## Path parameters - `serviceId` string, required ## Request body - UserinfoRequest - `token` string, required — An access token. - `clientCertificate` string — Client certificate used in the TLS connection established between the client application and the userinfo endpoint. The value of this request parameter is referred to when the access token given to the userinfo endpoint was bound to a client certificate when it was issued. See [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens] (https://datatracker.ietf.org/doc/rfc8705/) for details about the specification of certificate-bound access tokens. - `dpop` string — `DPoP` header presented by the client during the request to the user info endpoint. The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. - `htm` string — HTTP method of the user info request. This field is used to validate the DPoP header. In normal cases, the value is either `GET` or `POST`. - `htu` string — URL of the user info endpoint. This field is used to validate the DPoP header. If this parameter is omitted, the `userInfoEndpoint` property of the service is used as the default value. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. - `uri` string — The full URL of the userinfo endpoint. - `message` string — The HTTP message body of the request, if present. - `headers` Pair[] — HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature. - `key` string — The key part. - `value` string — The value part. - `targetUri` string — The target URI of the userinfo request, including the query part, if any. - `dpopNonceRequired` boolean — The flag indicating whether to check if the DPoP proof JWT includes the expected `nonce` value. If this request parameter is set to `true` or if the service's `dpopNonceRequired` property is set to `true`, the `/auth/userinfo` API checks if the DPoP proof JWT includes the expected `nonce` value. In this case, the response from the `/auth/userinfo` API will include the `dpopNonce` response parameter, which should be used as the value of the DPoP-Nonce HTTP header. - `requestBodyContained` boolean — The flag indicating whether the userinfo request contains a request body. ## Response `200` User info retrieved successfully - UserinfoResponse - `resultCode` string — The code which represents the result of the API call. - `resultMessage` string — A short message which explains the result of the API call. - `action` 'INTERNAL_SERVER_ERROR' | 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'OK' — The next action that the authorization server implementation should take. - `claims` string[] — The list of claims that the client application requests to be embedded in the ID token. - `clientId` integer — The ID of the client application which is associated with the access token. - `clientIdAlias` string — The client ID alias when the authorization request for the access token was made. - `clientIdAliasUsed` boolean — The flag which indicates whether the client ID alias was used when the authorization request for the access token was made. - `responseContent` string — The content that the authorization server implementation can use as the value of `WWW-Authenticate` header on errors. - `scopes` string[] — The scopes covered by the access token. - `subject` string — The subject (= resource owner's ID). - `token` string — The access token that came along with the userinfo request. - `properties` Property[] — The extra properties associated with the access token. - `key` string — The key part. - `value` string — The value part. - `hidden` boolean — The flag to indicate whether this property hidden from or visible to client applications. If `true`, this property is hidden from client applications. Otherwise, this property is visible to client applications. - `userInfoClaims` string — The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object. - `serviceAttributes` Pair[] — The attributes of this service that the client application belongs to. - `key` string — The key part. - `value` string — The value part. - `clientAttributes` Pair[] — The attributes of the client. - `key` string — The key part. - `value` string — The value part. - `consentedClaims` string[] — the claims that the user has consented for the client application to know. - `requestedClaimsForTx` string[] — Get names of claims that are requested indirectly by *"transformed claims"*. A client application can request *"transformed claims"* by adding names of transformed claims in the `claims` request parameter. The following is an example of the `claims` request parameter that requests a predefined transformed claim named `18_or_over` and a transformed claim named `nationality_usa` to be embedded in the response from the userinfo endpoint. ```json { "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "userinfo": { "::18_or_over": null, ":nationality_usa": null } } ``` The example above assumes that a transformed claim named `18_or_over` is predefined by the authorization server like below. ```json { "18_or_over": { "claim": "birthdate", "fn": [ "years_ago", [ "gte", 18 ] ] } } ``` In the example, the `nationalities` claim is requested indirectly by the `nationality_usa` transformed claim. Likewise, the `birthdate` claim is requested indirectly by the `18_or_over` transformed claim. When the `claims` request parameter of an authorization request is like the example above, this `requestedClaimsForTx` property will hold the following value. ```json [ "birthdate", "nationalities" ] ``` It is expected that the authorization server implementation prepares values of the listed claims and passes them as the value of the `claimsForTx` request parameter when it calls the `/api/auth/userinfo/issue` API. The following is an example of the value of the `claimsForTx` request parameter. ```json { "birthdate": "1970-01-23", "nationalities": [ "DEU", "USA" ] } ``` - `requestedVerifiedClaimsForTx` array[] — Names of verified claims that will be referenced when transformed claims are computed. - string[] - `transformedClaims` string — the value of the `transformed_claims` property in the `claims` request parameter of an authorization request or in the `claims` property in a request object. - `clientEntityId` string — The entity ID of the client. - `clientEntityIdUsed` boolean — Flag which indicates whether the entity ID of the client was used when the request for the access token was made. - `dpopNonce` string — The expected nonce value for DPoP proof JWT, which should be used as the value of the `DPoP-Nonce` HTTP header. - `metadataDocumentLocation` string, uri — The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. - `metadataDocumentUsed` boolean — Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. ## Other responses - `400` - `401` - `403` - `429` — The request exceeded the request rate permitted for the endpoint. - `500` ## Changes - **2026-08-03** `7ad74ab64749` — 1 info - added the non-success response with the status `429` - **2025-12-18** `504771740022` — 2 info - added the optional property `metadataDocumentLocation` to the response with the `200` status - added the optional property `metadataDocumentUsed` to the response with the `200` status [Change history](https://skmtc.dev/authlete/apis/authlete-api/changes/api/:serviceId/auth/userinfo/post.md) --- [API](https://skmtc.dev/authlete/apis/authlete-api.md) · [All operations](https://skmtc.dev/authlete/apis/authlete-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/authlete/authlete-api/revisions/7ad74ab64749/schema)