Oauth 2.0
All endpoints for retrieving a Corsano member's data require successful authorization via the OAuth 2.0 protocol. IETF RFC-6749 documents the full standard. While we will not explain OAuth 2.0 generally in this section, we will demonstrate how to use it to authorize an app's access to a Corsano member's data after the member grants consent.
Any subsequent references to OAuth in this documentation will be referring to OAuth 2.0.
We recommend you use a library to manage the details of the OAuth flow. You can find recommended libraries in a variety of programming languages here.
Pre-requisite
Before starting, you need to contact Corsano Support to obtain client_id and client_secret for your application. Please write to sabir@corsano.com, provide the name of your application, redirect_uri and the URL to the privacy policy of your application.
Required Information for OAuth
Client ID
The client_id
string will be provided to you by support.
Client Secret
The client_secret
string will be provided to you by support.
Authorization URL
This Corsano URL prompts a user to authorize your app to access the Corsano member's data. After the member grants authorization, Corsano will respond with an authorization code.
Token URL
This Corsano URL provides your app with the authorization code from the authorization URL after the Corsano member authorizes your app to access their Corsano data. This endpoint provides an access token in exchange for the authorization code.
Response Type
Parameter response_type
should be equal to code
Redirect URI
Corsano will redirect the member to the Redirect URL after they authorize your App to access the request scopes. You must register the Redirect URL in the Corsano Developer Dashboard.
A valid URL will take the form of https://corsano.com/example/redirect
or cardiomood://example/redirect
.
Note: Your OAuth library may reference Redirect URL
as a Callback URL
.
Example of Authorization URL
https://api.health.cloud.corsano.com/oauth/authorize?client_id=63177104986024782d5bb7e2&redirect_uri=http%3A%2F%2Flocalhost%2Foauth-redirect&response_type=code
When user visits this address Corsano will request from user permissions for your app to make requests on behalf of this user.
After user clicks Authorize button he or she will be redirected to redirect_uri passed in query parameters.
Parameter code
will be passed in this redurect_uri
.
Request An Access Token
We highly recommend using a library to manage the flow. There are available libraries in many programming languages.
The steps that the library will follow are:
- Your application will send a request to the Authorization URL for an authorization code.
- Corsano prompts the member to log in with their Corsano credentials.
- The member will confirm they authorize access to your app.
- Corsano will respond to the Redirect URL with an authorization code.
- Your application will send a request to the Token URL, exchanging the authorization code for an access token.
Sample POST Request Payload
{
"grant_type": "authorization_code",
"client_id": "631XXXXXXXXXXbb7e2",
"client_secret": "Vg78hYSECRETSECRETIxkhc",
"redirect_uri": "http://localhost/oauth-redirect",
"code": "def50200744cd95f2fa311ebd761f361d64d4144e250822d80db3d....."
}
Sample POST Response Payload
{
"token_type": "Bearer",
"expires_in": 31536000,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ....",
"refresh_token": "def502009078aaf34f7d01c04d390c395089f...."
}
Using An Access Token
After receiving an access token, all requests must include the access token.
Your app should pass the access token as a Bearer
token in the Authorization
header.
Corsano will return the requested data if the access token is successfully verified.
However, if the token is invalid, Corsano returns a 401 - Unauthorized
response.
Access Token Expiration
Access tokens are only valid for some time. Corsano provides the token expiry in the expires_in
parameter (in seconds). After the token expires, your app must refresh the token.
Refreshing an Access Token
Access tokens are short-lived, depending on the expires_in
value. Corsano will
respond with a (401 - Unauthorized) HTTP status code
if your app sends a request with an expired access token.
When the access token is expired, you can no longer use it and must refresh the token. If you do not want to wait for the token to expire before refreshing, you can refresh the complete set of access tokens regularly. One strategy is to execute refreshing access tokens using a background cron job.
Existing access tokens are invalidated once your app uses the refresh token to generate a new access token. The access token from the refresh response is now the valid access token, and your app can use the new access token for future requests. Similarly, the refresh token from the refresh response is now the valid refresh token, and your app must use the new refresh token on the subsequent refresh request.
Another advantage to refreshing tokens in a recurring job is that it limits the likelihood of issues occurring with multiple concurrent requests attempting to refresh an expired token. When your app makes simultaneous refresh token requests, the first refresh request that reaches Corsano will succeed. The second request would fail because the first request invalidates the refresh token.
Corsano provides your app with a refresh_token
after completing the OAuth 2.0 flow.
Required Information To Refresh
Refresh Token Endpoint
The Corsano URL where your app sends a POST request including the refresh token in exchange for a new access token.
Refresh Token
During the OAuth authorization flow, Corsano returns a refresh_token
that your app uses to refresh expired access tokens.
Client ID
The Client ID is a unique identifier for your Client app. Your app uses this ID to authenticate with Corsano. You can create and manage this ID in the Corsano Developer Dashboard.
Client Secret
The Client Secret is a secret value that accompanies a Client ID. You can view the Client Secret in the Corsano Developer Dashboard.
Grant Type
grant_type
parameter should be equal to refresh_token
Sample POST Request Payload
{
"grant_type": "refresh_token",
"client_id": "63177XXXXXXXXXXXX7e2",
"client_secret": "Vg78hYA8ASECRETSECRET0oaIxkhc",
"refresh_token": "def502009078aaf34f7d01c04d390c3..."
}
Sample POST Response Payload
{
"token_type": "Bearer",
"expires_in": 31536000,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni....",
"refresh_token": "def50200c027b235df5943950b5d52ff...."
}
We prepared a tutorial for you how to use Oauth 2.0 with Corsano.