OAuth Integration

OAuth Authorization

This document describes the flow between 3rd-party application and EXchange.

OAuth Client Register

To get user authorization through OAuth, your app must be registered on EXchange.

Please contact administrator to register.

Initiate Authorization Request

GET https://f1cx.com/oauth/authorize?client_id=<your_client_id>&redirect_uri=<registered_rediret_uri>&response_type=code&scope=<scopes>

'scope' is the authorizations you want to request. EXchange supports 3 scopes:

  • profile: basic user informations
  • history: user trades history
  • trade: buy/sell on markets

e.g. your app want to request for profile and history authorization:

scope=profile+history+trade

If user grants the authorizations your app requested, EXchange will generate a auth code and pass it back to redirect_uri.

Get User Token

With auth code, your app can get user token (APIv2 access/secret key) by:

POST https://f1cx.com/oauth/token
Params: client_id=<your_client_id>&client_secret=<your_client_secret>&code=<auth_code>&grant_type=authorization_code&redirect_uri=<registered_rediret_uri>

After validate the request, EXchange will return a user token and a refresh token. User token is a string including APIv2 access/secret key, in the format below:

<access_key>:<secret_key>

Split user token with colon ':', you get APIv2 access/secret key, with which you can access user authorized resources through APIv2.

Refresh token is used when user token (APIv2 access/secret key) is expired, please keep it in safe place.

For more information about APIv2, please visit APIv2 document.

Refresh User Token (APIv2 access/secret key)

The user token you get is valid for 4 hours. When you access user resources with expired user token, EXchange will return a error message with specific error code 2010:

{"error"=>{"code"=>2010, "message"=>"The access key xxxxx has expired."}}

When you see this error, get a new user token using the refresh token you got in last step:

POST https://f1cx.com/oauth/token
Params: client_id=<client_id>&client_secret=<client_secret>&grant_type=refresh_token&refresh_token=<refresh_token>

REMINDER

Do NOT keep any of client id, client secret, or refresh token on user devices. Keep them safe under your control.

References

  • http://zh.wikipedia.org/wiki/OAuth
  • http://oauth.net/