Authentication

iHealth OpenAPI V2 uses the OAuth 2.0 protocol for simple, but effective authentication and authorization. OAuth 2.0 is much easier to use than previous schemes; developers can start using the iHealth OpenAPI V2 almost immediately. The one thing to keep in mind is that all requests to the API must be made over SSL (https:// not http://)


Do you need to authenticate?

For the most part, iHealth’s API only requires the use of a client_id. A client_id simply associates your server, script, or program with a specific application. However, some requests require authentication - specifically requests made on behalf of a user. Authenticated requests require an access_token. These tokens are unique to a user and should be stored securely. Access tokens may expire at any time in the future.

Receiving an access_token

In order to receive an access_token, you must do the following:
  1. Direct the user to our authorization url.
    • If the user is not logged in, they will be asked to log in.
    • The user will be asked if they’d like to give your application access to his/her iHealth data.
  2. The server will redirect the user in one of two ways that you choose:
    • Server-side flow (recommended):Redirect the user to a URI of your choice. Take the provided code parameter and exchange it for an access_token by getting the code to our access_token url.

Server-side (Explicit) Flow

Using the server-side flow is quite easy. Simply follow these steps:

Step One: Direct your user to our authorization URL

The URL the 3rd party company would use for their user authorization,
http://sandboxapi.ihealthlabs.com/OpenApiV2/OAuthv2/userauthorization/
meanwhile, there are some parameters should come along with the URL above,

Required Parameters:

Parameter

Description

client_id

The ID for the client request(From the 3rd party company)

response_type

The type of request, it is required. The value is ‘code’.
Based on the OAuth 2.0, this will be used in the first stage, to request
more parameters that are used in the future stages. (Please see section
1.1.1)

redirect_uri

Your redirect URI's host and path MUST match exactly (including trailing slashes) to your registered redirect_uri. You may also include additional query parameters in the supplied redirect_uri, if you need to vary your behavior dynamically.

APIName

The API name has one or more value, they should be separated by space

Note that your redirect URI's host MUST match exactly (including trailing slashes) to your registered redirect_uri. You may also include additional query parameters in the supplied redirect_uri, if you need to vary your behavior dynamically. Examples:
http:// yourcallback.com/?this=that =>(URL encode)
http%3a%2f%2f+yourcallback.com%2f%3fthis%3dthat

Optional Parameters:

Parameter

Description

RequiredAPIName

The input format is the same as APIName. When displayed in the
authentication page, it is must be selected

IsNew

If the value of parameter is "true", the system will be auto redirected to the sign up page.

The sample of the request:

http://sandboxapi.ihealthlabs.com/OpenApiV2/OAuthv2/userauthorization/?client_id=4cdeb7844e*****&response_type=code&redirect_uri=http%3a%2f%2f+yourcallback.com%2f%3fthis%3dthat&APIName=OpenApiBP&RequiredAPIName=OpenApiBG+OpenApiBP&IsNew=true

Step Two: Receive the redirect from iHealth OpenAPI

Once a user successfully authenticates and authorizes your application, we will redirect the user to your redirect_uri with a code parameter that you’ll use in step three.

Parameter

Description

code

It is used to get the value of AccessToken. It is expired after 10 minutes

The sample of the response:

Note that your redirect URI's host and path MUST match exactly (including trailing slashes) to your registered redirect_uri. You may also include additional query parameters in the supplied redirect_uri, if you need to vary your behavior dynamically. Examples:

REGISTERED REDIRECT URI

REDIRECT URI SENT TO /AUTHORIZE

VALID?

http://yourcallback.com/

http://yourcallback.com/

yes

http://yourcallback.com/

http://yourcallback.com/?this=that

yes

http://yourcallback.com/?this=that&another=true

http%3a%2f%2fyourcallback.com%2f%3fthis%3dthat%26another%3dtrue

no

http://yourcallback.com/?this=that&another=true

http://yourcallback.com/?this=that&another=true

no

http://yourcallback.com/callback

http://yourcallback.com/callback/?type=mobile

yes

If your request for approval is denied by the user, then we will redirect the user to your redirect_uri with the following parameters:
error: access_denied
error_description: The user denied your request
http://your-redirect-uri?error=access_denied&error_description=The+user+denied+your+requestIt is your responsibility to fail gracefully in this situation and display a corresponding error message to your user.

 

Step Three: Request the access_token

In the previous step, you’ll have received a code which you’ll have to exchange in order to receive an access_token for the user. In order to make this exchange, you simply have to pass this code, along with some app identification parameters to our access_token endpoint.

The Request Content

Required Parameters:

Parameter

Description

client_id

Your client id

client_secret

Your client secret

grant_type

authorization_code is currently the only supported value

redirect_uri

Your redirect URI's host and path MUST match exactly (including trailing slashes) to your registered redirect_uri. You may also include additional query parameters in the supplied redirect_uri, if you need to vary your behavior dynamically.

code

The exact code you received during the authorization step.

Optional Parameters:

Parameter

Description

client_para

The same value to request. If it is not defined by request, the result will be an empty string

The sample of the request

The Response Content

After the request is verified by iHealth OpenAPI V2, the information of AccessToken will be sent out to 3rd party company in the format of .json, the details are:

Parameter

Description

APIName

The authorized API name

AccessToken

The token for access

Expires

The expired time of AccessToken

RefreshToken

A new AccessToken will be applied after the old one is expired. The new AccessToken, Expires, and APIName will be coming with the RefreshToken

UserID

Unique Identifier

client_para

The same value to request. If it is not defined by request, the result will be empty string

The sample of the response

{
"APIName": "OpenApiWeight OpenApiBPLittle OpenApiWeightLittle OpenApiActive OpenApiBG OpenApiSpO2",
"AccessToken": wo*PaoQkLMSdkV-Zqx-53jTPdgnF02gUUHoYzQo"*****",
"Expires": 172800,
"RefreshToken": "vGQentnJBO1kz9WNGBYGAPyqXE5CvKCRaMcf"*****",
"UserID": "05dffbe0dd*****",
"client_para": "xxx"
}

Sending RefreshToken and requesting new AccessToken

The Request Content

RefreshToken is used to acquire the new AccessToken after the old one expired. The process is to transfer the parameters below to iHealth OpenAPI V2 server.
The url is: http://sandboxapi.ihealthlabs.com/OpenApiV2/OAuthv2/userauthorization/
After the processing, our server will send the new AccessToken, in format of JSON, back to the redirect_uri.

Required Parameters:

Parameter

Description

client_id

The ID for the client request

client_secret

The key for the request

redirect_uri

That your redirect URI's host and path MUST match exactly (including trailing slashes) to your registered redirect_uri. You may also include additional query parameters in the supplied redirect_uri, if you need to vary your behavior dynamically.

response_type

The type of request, it is required. The value is ‘refresh_token’.
This parameter is for AccessToken request (Please see the section 1.3.1)

refresh_token

The key for the request of AccessToken
The latest RefreshToken from 1.2.2 returned value or from 1.3.2 returned value.

UserID

Unique Indentifier

Optional Parameters:

Parameter

Description

client_para

The same value to request. If it is not defined by request, the result will be empty string

The sample of request

The Response Content

The following is the detail description of the returning messages (same as 1.2.2)

Parameter

Description

APIName

The authorized API name

AccessToken

The token for access

Expires

The expired time of AccessToken

RefreshToken

A new AccessToken will be applied after the old one is expired. The new AccessToken, Expires, and APIName will be coming with the RefreshToken.

client_para

The same value to request. If it is not defined by request, the result will be empty string.

The sample of the response

{
"APIName": "OpenApiWeight OpenApiBPLittle OpenApiWeightLittle OpenApiActivity OpenApiBG OpenApiSpO2",
"AccessToken": "gfd21mA0k4u95xLS2TccG-eSKWHFJivlHkuNbXh-ww0Xny69-8**MDX0*****",
"Expires": 172800,
"RefreshToken": "5T-NU0kTQom9Pkb48DkjgEQ9dGX0-v5JZS7Db-C7itBgFQzBdpZ*EXqA*****",
"UserID": "05dffbe0dd*****",
"client_para": "xxx"
}