📘

NOTE

Please use the table of contents on the right side of this page to quickly navigate to a desired section.

Security and Authorization

Please note that Optum uses OAuth2 specification to establish a secure connection with our API users; our APIs are private and secure and can be accessed using unique credentials to generate a Bearer token.

👍

REQUIRED

• Credentials — your unique identity in the Intelligent Medical Network API ecosystem
• Bearer token — to securely access our APIs
• Sandbox testing — to ensure your integration works before going live

API components

• Sandbox URL

https://sandbox-apigw.optum.com/

• Production URL

https://apigw.optum.com/

Create sandbox

The sandbox environment allows you to familiarize yourself with our APIs and test our APIs before subscribing and enrolling to our API products, and integrating for real-time usage in your production environment.

Go to Request Sandbox Access and select the API product of your choice and submit the form.

We will provide you a set of unique credentials (client_id and client_secret) specific to your sandbox API environment, API product, and to your organization. Use the unique credentials to generate a Bearer token to securely access our APIs.

❗️

CAUTION

Carefully guard your API access credentials. Avoid sharing them with others.

📘

NOTE

DO NOT perform load testing or production data testing in the sandbox environment. Please use the sandbox ONLY to view test API responses to HTTP requests using our predefined values and to familiarize yourself with our APIs.

To perform load testing and production data testing, we recommend using our APIs in production environment.

📘

API TESTING/USING

• In our developer portal TryIt! interface
  • You need to reapply the Bearer token within the Bearer token expiry span by entering it in the CREDENTIALS box to test/use different APIs.
• In your development platform
  • The generated Bearer token need not be reapplied or re-entered to test/use different APIs; the same Bearer token will be used across all transactions during the full token life span, and you can automatically refresh the token just before it expires.

Generate a Bearer token

❗️

CAUTION

Carefully guard your API access credentials. Avoid sharing them with others.

In developer portal Try It! interface

1. Click Generate Bearer token.
2. Enter the company-specific secure credentials provided:
   • grant_type: select client_credentials
   • client_id: your client_id
   • client_secret: your client_secret
3. Click Try It! under the cURL Request box.

A Bearer token with a lifespan of 3600 seconds will be generated (highlighted in yellow in the following figure) in the RESPONSE box below the Try It!.

Copy the Bearer token without the double quotes into a notepad for reusing within the Bearer token lifespan of 3600 seconds.

In your development platform

1. Download and import the required product OpenAPI Spec (for example, to access the OpenAPI spec, go to the required API Overview section >> click Download OpenAPI Spec) and import it into the API project in your development platform.

2. Under the product API collection folder, click the Generate JWT token with payload - Medical Network (/apip/auth/v2/token) endpoint.

3. Click the Body tab and enter the unique secure credentials.

   • grant_type: always client_credentials
   • client_id: your client_id
   • client_secret: your client_secret

4. Send the request to generate a Bearer token.

The Bearer token will be valid until the Bearer token expires to try the APIs.

📘

BEARER TOKEN LIFESPAN

The lifespan of a Bearer token is 3600 seconds for both sandbox and production environments.

We recommend automating transactions to use 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.

Perform API health check

The /healthcheck endpoint verifies that the connection to the API server is established and the API is operational. Use your Bearer token to perform API health check.

In developer portal

1. Click /healthcheck endpoint under the product's API reference.
2. Paste the Bearer token (generated as mentioned in the previous section), in the CREDENTIALS >> Bearer box as mentioned in the Generate a Bearer token section above.
3. Click Try It! under the cURL Request box.

If the request was successful, the response shows such as, {"version": "v1","status": "OK"} in the RESPONSE box to indicate that the APIs are operational and are accessible. If the request failed, the reason shows in the RESPONSE box as listed in the HTTP Status Codes section at the end of this page or click the link in the TOC on the right.

Note that each API message depends on the API being tested/used.

If you received a response other than 200 OK, the API test failed. Please submit a support ticket with Optum.

❗️

CAUTION

Please do not submit PHI or PII data in the TryIt! interface (sandbox environment).

In your development platform

1. Download our OpenAPI Spec (for example, to access a product OpenAPI spec you are using/testing, go to the required API Overview section >> click Download OpenAPI Spec.) and import it into the API project in your development platform.
2. Generate a Bearer token as mentioned in the previous section (see).
3. Now, click the /healthcheck endpoint and send it view if the connection to the API server was established and if the API is operational.

Subscribe to live and mock data testing in sandbox environment

1. To test live and mock data testing, you must have purchased an API that shows a “subscribed” status in your AI Marketplace account. Please work with your API consultant to associate the provider TIN(s) before sending live data to the sandbox environment.
2. Use your sandbox unique credentials (client_id and client_secret) (mentioned in the create a sandbox section above) 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. You 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 returns mock responses.

Integrate our APIs in your production environment

After successful sandbox testing, you can integrate our APIs for real-time usage in your production environment by subscribing and enrolling to an API product of your choice and select the contract term at Optum AI Marketplace. Our business and technical teams support you through each step of the implementation process and through post-production.

We will provide you a set of unique credentials (client_id and client_secret) specific to your production API environment, API product, and to your organization to generate a Bearer token to securely access our APIs.

If you need help with this process reach out to @Contact us.