POST /oauth/userinfo

Returns information about the authenticated user. Uses HTTP POST.

The platform's OAuth Provider supports retrieval of claims about the end-user via its UserInfo endpoint. This API is an OAuth 2.0-protected resource. To obtain the requested claims about an end-user, the Client should make a request to the UserInfo API using an Access Token obtained through OpenID Connect Authentication. These Claims are normally represented by a JSON object that contains a collection of name and value pairs for the Claims.

The Client can include the access token in the request parameters, query, or post, depending on the HTTP method used to invoke the UserInfo API or as an Authorization header with Bearer scheme.

Note: We recommend that the request use the HTTP GET method (GET /oauth/userinfo), sending the access token in the Authorization header. For information on why you might choose one or the other, see OAuth Operations: GET or POST?

Authorization Roles/Permissions: Anyone can run this operation.

This topic includes the following sections:

HTTP Method

POST

URL

https://{oauth-provider-url}/oauth/userinfo

Sample Request

The access token can be sent in the query parameters, as an Authorization header, or as POST body.

The first example below shows a request for the user info, with an access token sent in the request URL.

Request URL #1: access token is in parameter

https://{oauth-provider-url}/oauth/userinfo?access_token={bearer_token_value}

Request URL #2: access token is in request body:

https://{oauth-provider-url}/oauth/userinfo

Sample request headers

The example below shows the access token sent in the Authorization header (for either GET or POST). But if the token is sent as a request parameter, or in the request body, the Authorization header is not needed.

Host: docexample.akana.rcoaless.com
Authorization: Bearer {bearer_token_value}
Accept: application/json
Content-Type: application/x-www-form-urlencoded

Sample request body (for request URL #2)

The example below shows the access token sent in the request body

access_token={bearer_token_value}

Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header	Description
Accept	application/json
Content-Type	application/x-www-form-urlencoded
Host	The host header for the API call, with the server hostname.
Authorization	The Authorization header, with the token type and token content.

Request Parameters

Parameter	Parm Type	Data Type	Required	Description
access_token	query or body	string	Optional	The access token that was received from the authorization server after the user was authenticated.

Response

If successful, this operation returns HTTP status code 200, with the user info.

Sample Response

The sample response below shows successful completion of this operation.

Sample response headers: application/json

Content-Type: application/json
Date: Fri, 18 Sep 2020 16:35:21 GMT

Sample response body: application/json

{
  "sub": "jmead",
  "mail": "jmead@akana.rcoaless.com",
  "$EMAIL": "jmead@akana.rcoaless.com",
  "$FULLNAME": "Jane.Mead",
  "cn": "Jane Mead"
}

Response Headers

For general information on response header values, refer to HTTP Response Headers.

Header	Description
Content-Type	application/json

Response Body

The response body is the userinfo. Exact contents depend on the OAuth Provider.

The response body includes the UserInfo claims, returned in a JSON object. The UserInfo claims include:

• Standard claims as defined in the OpenID Connect specification.
• Possibly, custom claims returned from specific identity providers.

The specific content of the response payload might vary according to the resource owner and also the scopes that are used to get the token.

The sub (subject) claim is always included in the UserInfo response. Other claims might be present, depending on the authentication response from the specific identity provider.

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

Item	Value
401	This operation might return a 401 for any of the following reasons: The request does not contain an access token (query/form parameter or Authorization header) The access token is invalid The access token is valid but was not obtained through OpenID Connect Authentication (openid scope was not part of the end-user authorization)
404	This operation might return a 404 for any of the following reasons: OpenID Connect is not enabled in the OAuth provider The host name is not mapped to the OAuth provider correctly The URL is accessed over HTTP but the provider is configured to accept only HTTPS requests
500	An error occurred processing the call.

More information about Akana OAuth API error messages.

Related Topics