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:
- 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.
- 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,
https://api.ihealthlabs.com:8443/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:
https://api.ihealthlabs.com:8443/OpenApiV2/OAuthv2/userauthorization/?client_id=4cdeb7844e*****&response_type=code&redirect_uri=http%3a%2f%2f+yourcallback.com%2f%3fthis%3dthat&APIName=OpenApiSleep%C2%A0OpenApiBP%C2%A0OpenApiWeight%C2%A0OpenApiBG%C2%A0OpenApiSpO2%C2%A0OpenApiActivity%C2%A0OpenApiUserInfo%C2%A0OpenApiFood%C2%A0OpenApiSport%C2%A0OpenApiT%C2%A0OpenApiHR&IsNew=False
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
|
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
|
|
token_type
|
The type of the token("bearer")
|
The sample of the response
{
"APIName": "OpenApiBG OpenApiSleep OpenApiActivity OpenApiBP OpenApiSpO2 OpenApiUserInfo OpenApiWeight OpenApiFood OpenApiSport OpenApiT OpenApiHR",
"AccessToken": wo*PaoQkLMSdkV-Zqx-53jTPdgnF02gUUHoYzQo"*****",
"Expires": 172800,
"RefreshToken": "vGQentnJBO1kz9WNGBYGAPyqXE5CvKCRaMcf"*****",
"UserID": "05dffbe0dd*****",
"client_para": "xxx",
"token_type": "bearer"
}
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: https://api.ihealthlabs.com:8443/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.
|
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.
|
|
token_type
|
The type of the token("bearer")
|
The sample of the response
{
"APIName": "OpenApiBG OpenApiSleep OpenApiActivity OpenApiBP OpenApiSpO2 OpenApiUserInfo OpenApiWeight OpenApiFood OpenApiSport OpenApiT OpenApiHR",
"AccessToken": "gfd21mA0k4u95xLS2TccG-eSKWHFJivlHkuNbXh-ww0Xny69-8**MDX0*****",
"Expires": 172800,
"RefreshToken": "5T-NU0kTQom9Pkb48DkjgEQ9dGX0-v5JZS7Db-C7itBgFQzBdpZ*EXqA*****",
"UserID": "05dffbe0dd*****",
"client_para": "xxx",
"token_type": "bearer"
}
An interface for unbundling openapi authorization application
The Request Content
Required Parameters:
|
Parameter
|
Description
|
|
client_id
|
The ID for the client request
|
|
client_secret
|
The key for the request
|
|
access_token
|
The token for access
|
|
user_openid
|
Unique ID of the user
|
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 the request
client_id=59451358deed42948******&client_secret=ce4ff9a6c5c44******&client_para=123&
user_openid=121212&access_token=*******4LefbUx8*******6frCebtmGtGoObPpohy*3
The Response Content
| Parameter
|
Description
|
|
BackValue
|
detail Information
|
|
Error
|
name of the message
|
|
ErrorCode
|
number
|
|
ErrorDescription
|
the detail description of this message
|
|
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
{
"BackValue": "success",
"Client_Para": "123",
"Error": "success",
"Expires": 0,
"RefreshToken": "success"
}