Authenticating API Calls

Kyruus Health relies on the OAuth 2.0 protocol for authorizing access to the APIs. Each request URL must include an access token to authenticate the client application that is sending API requests.

Authentication consists of two steps:

  1. Acquire an access token using your customer credentials.
  2. Pass the access token in API requests. You can pass an access token in the header of a request or in the URL itself.

Acquiring an Access Token

To acquire an access token, call the https://api.kyruus.com/oauth2/token endpoint from your application server, specify an HTTP POST method, and specify the following parameters to the endpoint:

  • client_id
  • client_secret
  • grant_type

The values for client_id and client_secret are the unique customer credentials that Kyruus Health provided for your project. Set grant_type to the string client_credentials.

For example, you can send a CURL request and specify your own values for the customer credentials:

curl -X POST https://api.kyruus.com/oauth2/token \
  -d client_id=<client_id> \
  -d client_secret=<client_secret> \
  -d grant_type=client_credentials

 

The request returns a new access token similar to this example:

{
  "token_type": "bearer",
  "access_token": "1dae88ab18b042f794a4ab939f647087",
  "expires_in":54000
}

 

The access token is valid for 15 hours (54000 seconds).

The APIs do not support a refresh token.

Important: Do not request a new access token for every search request. You can reuse an access token until it expires. Access tokens do not expire for 15 hours after they are issued. After it expires, request a new token. Requesting new tokens too frequently can degrade API performance (causing 5xx Internal Server errors).

Passing the Access Token in API Requests

Pass the access token in all subsequent API calls as per the OAuth 2.0 protocol. You can pass the token in one of two ways: either in the header of the request URL or by adding a URL query parameter for the access token to the request URL itself. Kyruus Health recommends passing the access token in the header.

Example Usage for v9

This example passes the access token as part of the header:

curl -k -v "https://api.kyruus.com/v9/broadway-health-demo/providers?name=A" -H 'Authorization: Bearer 
1dae88ab18b042f794a4ab939f647087'

This example passes the access token as a query parameter in the request URL:

curl -XGET 'https://api.kyruus.com/v9/broadway-health-demo/providers?access_token=1dae88ab18b042f794a4ab939f647087

 

Example Usage for v8

This example passes the access token as part of the header:

curl -k -v "https://api.kyruus.com/pm/v8/broadway-health-demo/providers?name=A" -H 'Authorization: Bearer 
1dae88ab18b042f794a4ab939f647087'

 

This example passes the access token as a query parameter in the request URL:

curl -XGET 'https://api.kyruus.com/pm/v8/broadway-health-demo/providers?access_token=1dae88ab18b042f794a4ab939f647087

Glossary

Access token: A temporary token required to access the APIs.

Application server: Part of a customer’s application executing on the customer’s infrastructure.

Customer credentials: A key/secret pair assigned to you for a project by Kyruus Health. In OAuth 2.0, customer credentials are client id and client secret. Client credentials are then used to acquire an access token.