Onboarding

To begin using the API, you’ll need to work with the Oscar ICHRA team to set up your integration. Email us at [email protected] to get started.

Obtaining Private Keys and Certificates

All API requests to the Oscar ICHRA APIs require mTLS authentication via private keys and certificates. Each partner will receive unique keys and certificates for each environment (staging and production). The key must be passed via request headers for all endpoints.

Please reach out to Oscar [email protected] to get API keys for ICHRA Connect.

Setting Up Access

Once you are set up by the Oscar Infra team, you should have the following items, where your company's name is in the place of "vendor-name" below:

Download the files and save them someplace you can reference them later.

Testing Connectivity

In a terminal window, navigate to the directory where your certificate & key files are stored.

Run the following command, where first-last should match the name on your keys and certificate. Make sure the base URLs match the key/certificate type you are testing.

curl -v --cert first-last.staging.vendors.external.pem --key first-last.staging.vendors.external.key https://ichra-api-staging.hioscar.com:444

You should get a response that looks like:

Welcome to Oscar's ICHRA API!

Key Management

• Private keys and certificates will be provisioned during onboarding.
• If you need a new key or wish to rotate an existing one, contact your Oscar account manager.
• Do not expose or share your private key publicly or embed it in client-side code.
• Oscar will rotate keys every 1-3 years and may revoke keys for security reasons.

Go-Live Checklist

Before switching to production, confirm:

• All 7 steps in Testing guide complete successfully in staging
• Your system correctly handles all three error categories (ACTIONABLE, RETRY, ESCALATE)
• You have received and securely stored your production mTLS certificate and key
• Your system retains application_id values for troubleshooting
• Your retry logic uses exponential backoff for 503 responses

Once ready, switch your base URL and certificate from staging to production:

https://ichra-api.hioscar.com:444/ichra-api/v1

Production only allows access to real members -- test member IDs will return 404.