Coins API can use OAuth2 to authenticate requests as legitimate and authorized. This requires the user to accept the scopes defined in your API client. If you do not wish to use your API secret to execute requests in behalf of a user, we recommend using this method.
Enabling OAuth2
Using the Coins API Dashboard you can get the necessary OAuth2 tokens to configure your application and begin using our API.
Important
- Make sure to request for approval of your OAuth application to [email protected] as this is required before doing any authenticated requests with OAuth2 authentication.
- If you're making a mobile or browser-based app, make sure to never place the client secret in the hands of your user.
- You can (and really, should ASAP) regenerate a new secret if your client secret gets compromised.
Scopes
OAuth2 requires the use of scopes. Each scope represents a feature in the API. In order to use a feature, the scope associated with that feature should be enabled in your application. Please make sure to select at least one scope. Applications without any scope cannot interact with the API.
Currently, the available scopes are:
- buyorder - Allows an application to use the Cash In APIs.
- sellorder - Allows an application to use the Cash Out APIs.
- history - Allows an application to view Cash In and Cash out transaction history.
- wallet_history - Allows an application to view the user's wallet transaction history.
- wallet_transfer - Allows an application to transfer funds from the user's wallet.
- user_identity - Allows an application to view the identity of the user.
We recommend using the least possible scopes that your application requires. If you decide you need more scopes later on, you should reauthorize your application with your users.
Application Authorization Flow
OAuth2 requires the developer to ask for user permissions before the application can make API calls. This is only done once, and then every time the token needs to be refreshed.
Direct your users to the url https://coins.ph/user/api/authorize
with the following query parameters:
- client_id - Select
show
on your chosen application's API Access dashboard. This is the API Key as displayed on the dialog. - response_type - Can either be
token
orcode
.token
is used for client-side flows, whilecode
is used for server-side flows. - state (optional) - A randomly generated unique value that's used to prevent cross-site request forgery attacks. We highly recommend that you pass this parameter and check for it when it's added as a query parameter on redirect.
- scope (optional) - Can be used to customize the scope of the token to be created. When not provided, the token will default to the scopes provided in the API Access page. Multiple scopes can be provided by separating each scope with a
+
, like so:buyorder+sellorder+history
. - redirect_uri - Should be the same as the Redirect URI defined in your API dashboard page.
A common example of a url for requesting user permission is as follows:
https://coins.ph/user/api/authorize?client_id=yourclientid&response_type=token&redirect_uri=example.com
Once a user approves your application, the user will be redirected to the redirect_uri
defined in the API dashboard. The redirect_uri
will then contain the following parameters appended to the url:
- access_token - The token to be attached to each request to prove authentication.
- token_type - The type of token returned.
- scope - The scopes of the provided token.
- state - The state parameter passed during authentication if passed.
The parameters are not appended to the url as GET parameters (ie. first parameter prefixed with a ?
). Instead, the first parameter is prefixed with a #
. This prevents our servers from logging the access token. It also means that you must use custom application logic to retrieve the access token.
Server Side Flow
Also known as Authorization Code Grant (section 4.1)
This flow is commonly used for applications that can't store the token in the client. The developer's application server is responsible for keeping track of its client's tokens. To use this flow, follow the steps described in Application Authorization Flow, with the response_type
parameter with the value code
. The user will then be redirected to the redirect_uri
you have provided, but instead of having an access_token
parameter, it will have code
attached. Additionally, The code
is used by the application server to retrieve an access token for a user. The code
can only be used once per user.
Access Token
The application server can retrieve an access_token
for the user by doing a POST request to the /user/oauthtoken
endpoint with the following parameters:
- client_id - Select
show
on your chosen application's API Access dashboard. This is the API Key as displayed on the dialog. - client_secret - Select
show
on your chosen application's API Access dashboard. This is Secret as displayed on the dialog. - code - The
code
retrieved from theredirect_uri
- grant_type -
authorization_code
is used to retrieve an access token. - redirect_uri - The
redirect_uri
as defined in your chosen application's API Access dashboard.
Upon completing the request, your application server should receive a json response with the key access_token
, which could then be used for subsequent API calls by including it in an Authorization HTTP header:
Authorization: Bearer useraccesstoken
Refresh Token
In addition to the access_token
being returned from the /user/oauthtoken
endpoint, the json response also contains a refresh_token
which can be used for getting a new access_token
. This is usually used for getting a new access_token
once it expires, or for invalidating the current access_token
in exchange for a new one.
Using the refresh_token
is almost the same as using code
to obtain an access_token
. Issue a POST request to the same endpoint, /user/oauthtoken
, with the following parameters:
- client_id - Select
show
on your chosen application's API Access dashboard. This is the API Key as displayed on the dialog. - client_secret - Select
show
on your chosen application's API Access dashboard. This is Secret as displayed on the dialog. - refresh_token - The
refresh_token
retrieved from the previous POST request to/user/oauthtoken
. - grant_type -
refresh_token
is used to use therefresh_token
to retrieve a new access token. - redirect_uri - The
redirect_uri
as defined in your chosen application's API Access dashboard.
Upon receiving the new access_token
, API requests can proceed as normal by including the access_token
in the Authorization
header.
Authorization: Bearer useraccesstoken
Server Side Flow Example
Example of a common server-side flow:
- Direct the user to
https://coins.ph/user/api/authorize?client_id=yourclientid&response_type=code&grant_type=authorization_code
- User selects "Allow"
- User is redirected to
https://yourredirecturl.com#code=somecode
- Client application retrieves the token from the url and sends it to the application server.
- Application server initiates a
POST
request to https://coins.ph/user/oauthtoken with an HTTP Content-Type header ofapplication/x-www-form-urlencoded
- The oauthtoken endpoint responds with a json that contains the key
access_token
- Application server stores this token in behalf of the user.
- The application server can now initiate API calls in behalf of the user, with the header
Authorization: Bearer useraccesstoken
for each API call.
Client Side Flow
Also known as Implicit Grant (section 4.2)
This flow is commonly used for applications that store the token in the client. Once you retrieve the access_token
from the user/api/authorize
endpoint, it can be used by adding this HTTP header for every API call:
Authorization: Bearer youraccesstoken
Client Side Flow Example
Example of a common client-side flow:
- Direct the user to
https://coins.ph/user/api/authorize?client_id=yourclientid&response_type=token
- User selects "Allow"
- User is redirected to
https://yourredirecturl.com#access_token=someaccesstoken&token_type=Bearer&state=&scope=buyorder+sellorder+history
- Client application retrieves the token from the url
- Client application can now initiate an API call, with the header
Authorization: Bearer someaccesstoken
for each API call.
Initiating API calls with OAuth2
Once the user or your application server has the access_token
an API call can
be made with the following required HTTP headers:
- Authorization - Authorization type followed by the access token ie.
Bearer token
- nonce - A number that can only be used once per user.