---
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.
### Description
This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfo)
of the authorization server in order to get information about the user that is associated with
an access token.
The response from `/auth/userinfo` API has various parameters. Among them, it is `action` parameter
that the authorization server implementation should check first because it denotes the next action
that the authorization server implementation should take. According to the value of `action`, the
service implementation must take the steps described below.
**INTERNAL\_SERVER\_ERROR**
When the value of `action` is `INTERNAL\_SERVER\_ERROR`, it means that the request from the authorization
server implementation was wrong or that an error occurred in Authlete. In either case, from the
viewpoint of the client application, it is an error on the server side. Therefore, the service
implementation should generate a response to the client application with HTTP status of "500 Internal
Server Error".
The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
(OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent`
as the value of`WWW-Authenticate` header.
The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details.
```
HTTP/1.1 500 Internal Server Error
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache
```
**BAD\_REQUEST**
When the value of `action` is `BAD\_REQUEST`, it means that the request from the client application
does not contain an access token (= the request from the authorization server implementation to
Authlete does not contain `token` parameter).
The value of `responseContent` is a string which describes the error in the format
of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the
userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
header.
The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details.
```
HTTP/1.1 400 Bad Request
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache
```
**UNAUTHORIZED**
When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has
expired, or is not associated with any subject (= any user account).
The value of `responseContent` is a string which describes the error in the format of [RFC
6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo
endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`
header.
The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details.
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache
```
**FORBIDDEN**
When the value of `action` is `FORBIDDEN`, it means that the access token does not include the
`openid` scope.
The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
(OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent`
as the value of`WWW-Authenticate` header.
The following is an example response which complies with RFC 6750. Note that OpenID Connect Core
1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo
Response](https://openid.net/specs/openid-connect-core-1\_0.html#UserInfoError) for details.
```
HTTP/1.1 403 Forbidden
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache
```
**OK**
When the value of `action` is `OK`, it means that the access token which the client application
presented is valid. To be concrete, it means that the access token exists, has not expired, includes
the openid scope, and is associated with a subject (= a user account).
What the userinfo endpoint implementation should do next is to collect information about the subject
(user) from your database. The value of the `subject` is contained in the subject parameter in the
response from this API and the names of data, i.e., the claims names are contained in the claims
parameter in the response. For example, if the `subject` parameter is `joe123` and the claims
parameter is `[ "given\_name", "email" ]`, you need to extract information about joe123's given name
and email from your database.
Then, call Authlete's `/auth/userinfo/issue` API with the collected information and the access token
in order to make Authlete generate an ID token.
If an error occurred during the above steps, generate an error response to the client. The response
should comply with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). For example, if the
subject associated with the access token does not exist in your database any longer, you may feel
like generating a response like below.
```
HTTP/1.1 400 Bad Request
WWW-Authenticate: Bearer error="invalid\_token",
error\_description="The subject associated with the access token does not exist."
Cache-Control: no-store
Pragma: no-cache
```
Also, an error might occur on database access. If you treat the error as an internal server error,
then the response would be like the following.
```
HTTP/1.1 500 Internal Server Error
WWW-Authenticate: Bearer error="server\_error",
error\_description="Failed to extract information about the subject from the database."
Cache-Control: no-store
Pragma: no-cache
```

## 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. This parameter is used as the value of the `@target-uri` derived component for HTTP message signatures ([RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)). Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and `@query-param` are computed from this parameter. When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter represents the URL of the userinfo endpoint, which usually serves as the target URI of the userinfo request. The only exception is when the access token is specified as a query parameter, as defined in [RFC 6750 Section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3). However, RFC 6750 states that this method "SHOULD NOT be used" unless other methods are not viable. If neither this `targetUri` parameter nor the `htu` parameter is specified, the `userInfoEndpoint` property of the service is used as a fallback.
  - `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. When the userinfo request must comply with the HTTP message signing requirements defined in the FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) if the userinfo request contains a request body. When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"` is included in the signature base, if the FAPI profile applies to the userinfo request. NOTE: The FAPI 2.0 Message Signing specification is not applied to the userinfo endpoint until its necessity is agreed upon by the industry (cf. [FAPI Issue 723](https://bitbucket.org/openid/fapi/issues/723)).

## 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. A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. In both cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties. ```json { "userinfo": { "given_name": { "essential": true }, "nickname": null, "email": { "essential": true }, "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null }, "id_token": { "auth_time": { "essential": true }, "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } } } ```` The value of this property is the value of the `userinfo` property in JSON format. For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. ```json { "given_name": { "essential": true }, "nickname": null, "email": { "essential": true }, "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null } ``` Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, the value of this property holds the former value.
  - `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`
- `500`

## Changes

- **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/8a534bc68775/schema)