The user attributes endpoint - Amazon Cognito
GET /oauth2/userInfoRequest parameters in headerExample – requestExample – positive responseExample negative responses

The user attributes endpoint

Where OIDC issues ID tokens that contain user attributes, OAuth 2.0 implements the /oauth2/userInfo endpoint. An authenticated user or client receives an access token with a scopes claim. This claim determines the attributes that the authorization server should return. When an application presents an access token to the userInfo endpoint, the authorization server returns a response body that contains the user attributes that are within the boundaries set by the access token scopes. Your application can retrieve information about a user from the userInfo endpoint as long as it holds a valid access token with at least an openid scope claim.

The userInfo endpoint is an OpenID Connect (OIDC) userInfo endpoint. It responds with user attributes when service providers present access tokens that your token endpoint issued. The scopes in your user's access token define the user attributes that the userInfo endpoint returns in its response. The openid scope must be one of the access token claims.

Amazon Cognito issues access tokens in response to user pools API requests like InitiateAuth. Because they don't contain any scopes, the userInfo endpoint doesn't accept these access tokens. Instead, you must present access tokens from your token endpoint.

Your OAuth 2.0 third-party identity provider (IdP) also hosts a userInfo endpoint. When your user authenticates with that IdP, Amazon Cognito silently exchanges an authorization code with the IdP token endpoint. Your user pool passes the IdP access token to authorize retrieval of user information from the IdP userInfo endpoint.

GET /oauth2/userInfo

Your app makes requests to this endpoint directly and not through a browser.

For more information, see UserInfo Endpoint in the OpenID Connect (OIDC) specification.

Request parameters in header

Authorization: Bearer <access_token>

Pass the access token in the authorization header field.

Required.

Example – request

GET /oauth2/userInfo HTTP/1.1
Content-Type: application/x-amz-json-1.1
Authorization: Bearer eyJra12345EXAMPLE
User-Agent: [User agent]
Accept: */*
Host: auth.example.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Example – positive response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: [Integer]
Date: [Timestamp]
x-amz-cognito-request-id: [UUID]
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Server: Server
Connection: keep-alive
{
    "sub": "[UUID]",
    "email_verified": "true",
    "custom:mycustom1": "CustomValue",
    "phone_number_verified": "true",
    "phone_number": "+12065551212",
    "email": "bob@example.com",
    "username": "bob"
}

For a list of OIDC claims, see Standard Claims. Currently, Amazon Cognito returns the values for email_verified and phone_number_verified as strings.

Example negative responses

Example – bad request

HTTP/1.1 400 Bad Request
WWW-Authenticate: error="invalid_request",
error_description="Bad OAuth2 request at UserInfo Endpoint"
invalid_request

The request is missing a required parameter, it includes an unsupported parameter value, or it is otherwise malformed.

Example – bad token

HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="Access token is expired, disabled, or deleted, or the user has globally signed out."
invalid_token

The access token is expired, revoked, malformed, or it's invalid.