Security and Authorization v3

This documentation describe how to use the platform's standard security API to request an access token that can be used to access other APIs on the platform. A downloadable specification is available as a reference to this implementation.

Access Control via Web Tokens

All Optum APIs on this platform are secured using JSON Web Tokens (JWT).

Security via TLS

All calls to Optum APIs are encrypted over HTTPS. Our APIs support connections using TLS version 1.2 or higher.

Authorization via OAuth2

Access to Optum APIs is controlled via OAuth2 using the client credentials grant. This is a secure authorization workflow that allows consumers to obtain a short-lived (two hours) access token that must be transmitted with subsequent API requests.

To obtain a token, consumers first need a client_id and client_secret. These credentials are provided during the customer onboarding process. To request access credentials, use either the Request Sandbox Access link or the Contact Us link to contact the Product Manager of a specific API.

Obtaining an Access Token

This section describes how to get an access token in a particular environment.

📘

Remember!

• Your-ClientId and Your-ClientSecret should be replaced with a valid set of credentials.
• URLs are environment-specific and may need to be modified according to the target environment.

The request body parameters (clientID, secret, and granttype) can only be sent in application/x-www-form-urlencoded format.

Example request:

curl --request POST \
     --url /auth/sntl/v1/token \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data client_id=<<Your-ClientId>> \
     --data client_secret=<<Your-ClientSecret>>

A successful call to this API will return a new access_token, which is used to authorize subsequent calls to other APIs on the platform. By default, the access_token will be valid for one hour from the time of its issuance.

Example response:

{
   "access_token": "xxxx",
   "expires_in": 7200,
	 "refresh_expires_in": 0,
	 "token_type": "Bearer",
	 "not-before-policy": 0,
	 "scope": "broker-read-token idp openid email profile"
}

The access token returned in the above response can be used to access APIs on this platform that are secured via the standard Authorization implementation. Calls to these APIs must include the following headers:

Authorization: Bearer <<Your-Access-Token>>