Add OAuth Endpoints
Athenahebalth supports the following standard OAuth endpoints in addition to authorize token endpoints:
Introspect
[ GET ] /oauth2/v1/introspect
Checks the status and content of a token (JWT). Introspection is most useful for checking the OAuth scopes granted with an access token or whether a token has expired.
Input Parameters
IMPORTANT: Endpoint requires client authentication. Refer to our documentation on the token authentication method applicable to your app.
* = required
| Parameter | Type | Description |
|---|---|---|
| token* | string | The value is an access token, ID token, or refresh token as returned by the token endpoint. |
| token_type_hint* | string | The value indicates the type of token provided in the token parameter: access_token, id_token, or refresh_token. |
Output Parameters
| Parameter | Type | Description |
|---|---|---|
| active | boolean | The value indicates whether the provided token is active or not. |
| exp | integer | Returned only if the provided token is active. The value is the token expiration date expressed in Unix time (seconds since January 1, 1970 UTC). |
| scope | string | Returned only if the provided token is active. The value is a space-delimited list of scopes granted to the provided token. |
| (various) | (various) | Output parameters may also include token claims and additional metadata on the provided token, varying with the type and status of the token. |
Public JWKS
[ GET ] /oauth2/v1/keys
Returns the public JWKS used to verify a token (JWT) signature. Refer to our documentation on token authentication using imported public JWKS for more details.
Input Parameters
* = required
| Parameter | Type | Description |
|---|---|---|
| client_id* | string | The value is your app’s OAuth client ID. The client ID must be provisioned for the athenaOne environment specified in the base URL of the authorize endpoint. |
Output Parameters
Logout
[ GET ] /oauth2/v1/logout
- Terminates an end user’s (patient’s or provider’s) login session in the athenahealth login widget, which otherwise expires after 10 minutes of idle time.
- This endpoint applies primarily to apps launched standalone from athenaOne for which an idle login session on a shared device could lead to inappropriate access to EHI.
- In contrast, provider-facing apps launched from athenaOne leverage the user’s athenaOne login session, where that login session is terminated when the user logs out through the athenaOne user interface.
Login sessions are distinct from token durations and terminating a login session will not invalidate any active access or refresh tokens. Terminating a login session ensures that the user will be forced to reauthenticate with the next authorize request made by your app.
Input Parameters
* = required
| Parameter | Type | Description |
|---|---|---|
| id_token_hint* | string | This value is an ID token obtained following authentication of the logged-in user. The endpoint looks specifically at the “sub” claim in this ID token, which it then matches against users with active login sessions. If there is a match, the user’s login session is terminated. |
| post_logout_redirect_uri | string | The value is the URI to which the end user will be redirected upon logout. The redirect URI must exactly match a post-logout redirect URI configured for your app’s OAuth client credentials during registration. |
| state | string | The value is a one-time use arbitrary string provided by your app and subsequently returned by the logout endpoint. The intent of this parameter, per OAuth specification, is for your app to compare the request and response values to prevent cross-site request forgery attacks. |
Output Parameters
| Parameter | Type | Description |
|---|---|---|
| state | string | The value is identical to the state parameter provided in your app’s logout request. |
References:
https://docs.athenahealth.com/api/guides/additional-oauth-endpoints