Authentication protocols: Optum Real APIs utilize OAuth 2.0 for secure authentication and data transfer. OAuth tokens function as bearer tokens for accessing our gateway

ClientID and secret key: You can request a ClientID and secret key for our sandbox endpoint prior to subscribing to an API or while waiting for your production ClientID and secret key, which are available via your Optum AI Marketplace account or email after you have subscribed to an API. The provider IT team must use the API credentials to generate bearer token for either sandbox endpoint or production endpoint.

📘

NOTE: You will have two sets of credentials:

• One for the sandbox — to help you test our APIs before signing a contract or after.
• One for production — provided after signing a contract or after processing a subscription.

These credentials are specific and unique to an API environment and your organization.

If you do not have your credentials, please reach out to your account manager or API consultant for further assistance.

How to access a sandbox

1. Request for sandbox account without any financial obligations. This will include ClientID and secret key for sandbox.
2. Generate an authorization/bearer token by passing Client ID and secret key "here" or use Postman.
3. Test our APIs using "try it" interface or postman. (Please refer to individual API Technical Reference Guide for additional details about "Try It" page)

Sandbox use for live and mock data testing

1. Customers must have purchased an API with status “subscribed” in the AI Marketplace account, please work with API consultant to associate provider TIN(s) before sending live data to sandbox environment.
2. Customers must use their sandbox credentials to send live data to the sandbox environment for the API purchased.
   At this point, responses will be based on the live data submitted to the sandbox environment as opposed to mock data preloaded to the sandbox environment.
3. The customer will retain the ability to query mock responses from a sandbox environment by using an optional request header called “environment”. By placing the value “sandbox" in the optional header, the request return mock responses.
   NOTE: Do not submit PHI or PII data in the TRY IT page.

Bearer token: Token should be generated using the API credentials Optum provides for sandbox access or production credentials received after subscribing to an API.

Generate an API token

Bearer token lifespan The lifespan of a bearer token is one hour (3600 seconds) for both sandbox and production environments.
We recommend automating transactions using the tokens generated over the token lifespan. Obtaining tokens for each transaction is less efficient and does not improve the security criteria for any transactions.

See sample request and response bearer token format below for reference:

Bearer token request header: **

Content-Type: application/json
Authorization: Bearer

Bearer token request and response example:

Bearer token request format

curl -X POST \ 

  '** (placeholder for URL)/**' \ 

  -H 'Content-Type: application/json' \ 

  -d '{ 

  "client_id": "<Your-ClientId>", 

  "client_secret": "<Your-ClientSecret>", 

  "grant_type": "client_credentials" 

}' 

Bearer token response example:

{ 

    "access_token": 

    "eyJraWQiOiIxIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhY2Nlc3NfdG9rZW4iOiJkc1JvRTMzSFYzbnpkYjh3ak1hWWtFUmY4VVF5IiwiYXVkIjoiYXBpUGxhdGZvcm0iLCJuYmYiOjE2MTA0OTMxMTAsImFwaV9wcm9kdWN0X2xpc3QiOlsiTU5fUHJvZHVjdF9DbGFpbVN0YXR1c192MiIsIk1OX1Byb2R1Y3RfRWxpZ2liaWxpdHlfdjMiLCJNTl9Qcm9kdWN0X1Byb2Zlc3Npb25hbENsYWltc192MyIsIlRQX1Byb2R1Y3RfVHJhZGluZ1BhcnRuZXJzX3Y3IiwiTU5fUHJvZHVjdF9SZXBvcnRzX3YxIiwiTU5fUHJvZHVjdF9BdHRhY2htZW50c192MSIsIk1OX1Byb2R1Y3RfSW5zdGl0dXRpb25hbENsYWltc192MSIsIk1OX1Byb2R1Y3RfUERfQ2xhaW1zU3RhdHVzX3YxIiwiTU5fUHJvZHVjdF9QRF9DbGFpbXNfdjEiLCJNTl9Qcm9kdWN0X1BEX0VsaWdpYmlsaXR5X3YxIiwiVFBfUHJvZHVjdF9UcmFkaW5nUGFydG5lciJdLCJhcHBsaWNhdGlvbl9uYW1lIjoiSU5fQVBJUF9NTl9DSENfVGVzdEFwcCIsImRldmVsb3Blcl9lbWFpbCI6ImNkcHRlYW1AY2hhbmdlaGVhbHRoY2FyZS5jb20iLCJpc3MiOiJodHRwczovL3NhbmRib3guYXBpcy5jaGFuZ2VoZWFsdGhjYXJlLmNvbSIsImV4cCI6MTYxMDQ5NjcxMCwiaWF0IjoxNjEwNDkzMTEwLCJqdGkiOiJjNjQ4ODBjMC1hZDFhLTQ1NzEtOGJjYi02YmI2NGQ1YWRlYTgifQ.t8YPbCuyn_CNXmMIwlIL0y14j-RqO1VsHSkahtXZrf5uURZ0grU_oDepwNeRKf2Sr8norTSEsKvjPSFHaKxb_U7yQ2g9UnyH5PA1X63-Lj5v8h38BdUk19p2GQBJSzmGPEyazvYoCCxSGZ68RN9kZb_WrQWObsrMyb1JFN_zeWa2j3YGgbBglZNO_Wt1Ty6ZQrDWcxeVMlbIRMDAKYBUrmmTTsIpHrol-5YzyYgZVBpO-Hxz_otD4t-_DRx5_cxLl4tG1qi7i2Ddb65eO3XxQU-Ibzb9bAT4HXIR3Ab735cTJMBlK9jCfDc0DDCBkpGAHwJV5rj0zOEitC1xciLt3g", 

 

    "token_type": "bearer", 

    "expires_in": 3600 

}