Introduction

VitalDB APIs use the OAuth2.0 protocol for authentication and authorization.

Overall Process

Your application must request a code and then extracts an access token from the response. Finally, your application can use the data from VitalDB APIs using the access token.

Login Page

Issue a code, which is required to get an access token. Used in “Sign in with VitalDB” service.

Endpoint

https://vitaldb.net/oauth2/login

Method

GET

Parameters

Please urlencode the parameter if it has any special characters.

Field	Type	Required	Description
client_id	String	Required	Client ID, please contact us to get a client ID
redirect_uri	String	Required	URI to be redirected after login succeeds. Redirected to: redirect_uri?code=xxxxxxxx&state=xxxxxxxx
state	String	Optional	Random String used to protect against CSRF (Cross-site Request Forgery). VitalDB server sends back the state parameter. If state parameters are different, CSRF detected.

Return Value

If successful, it redirected to redirect_uri?code=xxxxxxxx&state=xxxxxxxx

Field	Type	Description
code	String	A code (random string) which is required to issue an access token. The code will expire in 3 minutes.
state	String	Random String used to protect against CSRF (Cross-site Request Forgery). VitalDB server sends back the state parameter. If state parameters are different, CSRF detected.

Sample Codes

curl -i https://vitaldb.net/oauth2/login?client_id=xxxxxxx&redirect_uri=https://www.path-to-redirect.com/callback

Get Token

Issue an access token which is required to access VitalDB APIs.

Endpoint

https://vitaldb.net/oauth2/token

Method

POST

Parameters

Please urlencode the parameter if it has any special characters.

Field	Type	Required	Description
client_id	String	Required	Client ID, please contact us to get a client ID
client_secret	String	Required	Client Secret, please contact us to get a client secret
code	String	Required	A code issued by VitalDB Login API

Field	Type	Required	Description
id	String	Required	VitalDB user ID
pw	String	Required	VitalDB user password

Return Value

Content-type: application/json

Field	Type	Description
access_token	String	An access token which is required to access VitalDB APIs
token_type	String	Bearer type
expires_in	Number	= 3600. The access token expires in an hour.

Sample Codes

curl -v -d 'code=xxxxxxxxxxxx&client_id=xxxxx&client_secret=xxxxxxxx' https://vitaldb.net/oauth2/token

curl -v -d 'id=userid&pw=password' https://vitaldb.net/oauth2/token