Aetna Patient Access APIs Hero
Mark Lorenz


In this post:

  • Editorial commentary on how Aetna implemented their Patient Access APIs. It should be fun for software developers, healthcare wonks, and thinkbois.
  • References for fans of The Simpsons and Mitch Hedberg
  • A call to action: we need your help if you know someone with a Medicare Advantage plan from Aetna.

That's why I don't buy it, I don't need another step between me -and- toast.

I tried writing this without snarking on Aetna, because honestly of all the health insurance companies, Aetna is miles ahead in complying with the CMS 9115-F Patient Access and Interoperability rules. I'm sorry, I can't do it. There's still plenty to poke fun at.

Aetna: The best Patient Access APIs

The Aetna Patient Access APIs are live, but only for Medicare Advantage plans (not Medicare Part-D plans or ACA Exchange plans as is required)

Let's start with what Aetna got right:

  • The documentation for the Aetna API developer site was easy to find and it was easy to sign up for a sandbox account.
  • I did have to fill out an "access request" form (actually it was an excel workbook) explaining security practices (the rules allow this). It was annoying that I had to email it back to them, but they processed it quickly, so all good.
  • The developer support is 🔥. The Aenta team was very quick to responded to emails and their developers know what they're doing (far, far, exceeding my expectation)

How to work with Aetna's Patient Access APIs

Aetna making things more complicated than they need to be.


Then things get weird. OAuth flows for authorizing third party applications are clearly defined standards. There's no need to make simple things hard.

Aetna Patient Access OAuth Workflow

In OAuth workflows, the user experience is very simple- you've probably used OAuth to login with your Google, Twitter, or Facebook account somewhere. Behind the scenes, the website requesting authorization makes a few API calls to know where to send the user for authorization, and manage a temporary password (which OAuth calls a "token").

The Aetna authorization API endpoint requires an AUD parameter that's required and has to be a specific value...but doesn't actually modify the behavior of the API. It's that Mitch Hedberg skit about how the fancy breads have two wrappers. I don't need another step between me -and- toast.

The redirect_uri parameter is where the user is sent back to after authorization is granted and it's also required by the authorization endpoint, but it's totally ignored. The redirect_uri you configured in their portal is used instead. I'm sure this is security feature, but it's also confusing. Luckily, the redirect_uri can be easily updated in the developer portal- this is not true for other insurance companies.

The tape must have fallen off… There! Problem solved.

Lastly we have the Imperva CDN, that breaks the internet and only runs in the production environment! There is nothing more frustrating than code that works in the sandbox environment, but crashes in the production environment where it's MUCH harder to debug. No actually there is something worse: appliances that don't follow the rules of HTTP. Aetna's Imperva CDN adds an invalid header to the authorize response.

Notice that first line. Spaces are not valid in HTTP header field names. Strict HTTP parsing is a security feature. Having to disable it is an irony for sure. Remember that "access request" I had to fill out with the security assessment? 🤦‍♀️ When this crashes your code, it's the obtuse "check engine" light on your car. The tape must have fallen off… There! Problem solved. Your developers will "solve" this crash by adding insecureHTTPParser: true to their code. Does that sound secure?


After the user/member/patient authorizes, we need to get a token that serves as our password to the EOB. Normally OAuth tokens are short-lived (~5 minutes), but can be refreshed for a long time (often indefinitely). This dictates how long the app will be able to help the user/member/patient before they have to authorize again.

Aetna decided that their Sandbox environment would not include refresh tokens (so access is only available for 5 minutes) but that their documentation would include a refresh token 🤷. Will the production implementation include a refresh token? I don't know, we will need to find someone with an Aetna Medicare Advantage plan to test it out.


The EOB looks good. Nice job Aetna.

Wrapping up

I'm sure Aetna's actively working on their APIs, so I'll try to keep this updated. If I got it wrong, please email me

Do you know someone with an Aetna Medicare Advantage plan? Please send them to the HealthSouse home page. We may also be able to save your friend some money.

More about how HealthSouse helps

Still here? Thanks for reading! You seem like a nice person, who should send me an email: Encouragement and criticism are both welcome!