Authentication

The Rupa API uses OAuth2 to authenticate requests. Your practitioners will grant access to your application to access their Rupa Health account on their behalf. We support the standard OAuth authorization grant type to obtain an authorization code and then exchange it for a secure access token. The API also supports revoking tokens.

Overview

To get started with OAuth, the steps are:

1. Get your OAuth Credentials. To request authorization from practitioners, you'll need an OAuth Application with a CLIENT_ID and CLIENT_SECRET. We'll provide these for you.
2. Request authorization. You'll request permission from a practitioner to access their Rupa account by directing them to Rupa's authorization page.
3. Authorization grant. After granting authorization, the practitioner will then be redirected back to your app with an authorization code.
4. Authorization code exchange. Then you'll exchange the authorization code for an access token by making a request to Rupa's authorization server..
5. Use the API. Then you can use the access token to access the Rupa API.
6. Refresh the access token. Access tokens expire, so you'll use the refresh_token to get a new one.

Let's go through each of the steps.

1. Get your OAuth credentials.

To get started you'll need your CLIENT_ID and CLIENT_SECRET. A member of the Rupa team will provide these to you. You'll need to provide a REDIRECT_URI that Rupa will redirect practitioners to after they grant access to their account.

2. Request authorization

When you want to access a Rupa Practitioner's account, direct them to:

https://labs.rupahealth.com/oauth/authorize?
    client_id=CLIENT_ID&
    redirect_uri=REDIRECT_URI&
    response_type=code

The practitioner will be asked to login to their Rupa account. Then they'll be asked to grant your application access to their account. The practitioner will then either accept or deny your request.

You can customize the name and logo that appear on the authorization screen.

Currently, all OAuth authorizations request the same [read, write] scopes that provide access to all endpoints. More granular scopes will be introduced in the future, but we'll notify all apps nearer the time.

3. Authorization grant

If they accept, they'll be redirected back to the provided REDIRECT_URI with an authorization code in the ?code query parameter. If they choose not to except (by closing the tab or their browser), no redirect will occur.

For example, the redirected URL for redirect_uri=https://example.com will look like https://example.com/?code=abcdef.

4. Authorization code exchange

After successful authorization, the user will be redirected to your app along with a one-time authorization code embedded in the code query parameter. To exchange the code for an access token, use the Token endpoint. This endpoint will provide an access token for server-side authentication and a publishable key for browser-side authentication.

For example:

curl --request POST \
  --url https://api.rupahealth.com/oauth/token \
  --header 'Accept: multipart/form-data' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data code=some_authorization_code \
  --data client_id=123456 \
  --data client_secret=abcdef \
  --data grant_type=authorization_code
  --data redirect_uri=https://example.com

This will return an access_token:

{
  "access_token": "jooqrnOrNa0BrNWlg68u9sl6SkdFZg",
  "publishable_key": "pk_7bf3fca3e384960013f0cceae7c519ec86ac1143",
  "token_type": "Bearer",
  "expires_in": 36000,
  "refresh_token": "HNvDQjjsnvDySaK0miwG4lttJEl9yD",
  "scope": "read write"
}

5. Use the API

Now you have an access token, you can now make requests to the API by including the token in the Authorization header. For example, to use the Practitioner endpoint:

curl \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  https:/api.rupahealth.com/practitioners/me

Check out the API Reference to explore available endpoints.

6. Refresh the access token

Access tokens are valid for 10 hours (as indicated by the expires_in property of the token response). New access tokens can be created using the refresh_token grant type of the Token endpoint. To get a new token, pass the refresh_token given in a previous response:

curl --request POST \
  --url https://api.rupahealth.com/oauth/token \
  --header 'Accept: multipart/form-data' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=123456 \
  --data client_secret=abcdef \
  --data grant_type=redirect_token
  --data refresh_token=HNvDQjjsnvDySaK0miwG4lttJEl9yD

Revoke an access token (optional)

If you need to revoke an access token, during testing for example, see Revoke an access token.

Next

Next, learn how to use our Sandbox Environment.