{"_id":"56326ea3df556c0d00cd08f8","category":{"_id":"56326e9ddf556c0d00cd08cc","__v":1,"project":"544fc17e698ab40800b4f891","version":"56326e9cdf556c0d00cd08ca","pages":["56326ea3df556c0d00cd08f6","56326ea3df556c0d00cd08f7","56326ea3df556c0d00cd08f8"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-05-01T05:42:46.293Z","from_sync":false,"order":1,"slug":"authentication","title":"Authentication"},"version":{"_id":"56326e9cdf556c0d00cd08ca","project":"544fc17e698ab40800b4f891","__v":2,"createdAt":"2015-10-29T19:08:12.724Z","releaseDate":"2015-10-29T19:08:12.724Z","categories":["56326e9ddf556c0d00cd08cb","56326e9ddf556c0d00cd08cc","56326e9ddf556c0d00cd08cd","56326e9ddf556c0d00cd08ce","56326e9ddf556c0d00cd08cf","56326e9ddf556c0d00cd08d0","56326e9ddf556c0d00cd08d1","56326e9ddf556c0d00cd08d2","56326e9ddf556c0d00cd08d3","56326e9ddf556c0d00cd08d4","56d942ac337fd11300d6a251"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"collector","version_clean":"2.1.0","version":"2.1"},"project":"544fc17e698ab40800b4f891","__v":0,"user":"544fc065698ab40800b4f888","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-05-01T07:56:46.051Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"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.\n\n## Enabling OAuth2\n\nUsing the [Coins API Dashboard](https://coins.ph/user/api) you can get the necessary OAuth2 tokens to configure your application and begin using our API.\n\n> If you're making a mobile or browser-based app, make sure to never place the client secret in the hands of your user.\n\n> You can (and really, should ASAP) regenerate a new secret if your client secret gets compromised.\n\n## Scopes\n\nOAuth2 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.\n\nCurrently, the available scopes are:\n\n* **buyorder** - Allows an application to use the Cash In APIs.\n* **sellorder** - Allows an application to use the Cash Out APIs.\n* **history** - Allows an application to view Cash In and Cash out transaction history.\n* **wallet_history** - Allows an application to view the user's wallet transaction history.\n* **wallet_transfer** - Allows an application to transfer funds from the user's wallet.\n* **user_identity** - Allows an application to view the identity of the user.\n\nWe 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.\n\n## Application Authorization Flow\n\nOAuth2 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.\n\nDirect your users to the url `http://coins.ph/user/api/authorize` with the following query parameters:\n\n* **client_id** - Select `show` on your chosen application's [API Access](https://coins.ph/user/api) dashboard. This is the API Key as displayed on the dialog.\n* **response_type** - Can either be `token` or `code`. `token` is used for client-side flows, while `code` is used for server-side flows.\n* **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](https://coins.ph/user/api) page. Multiple scopes can be provided by separating each scope with a `+`, like so: `buyorder+sellorder+history`.\n* **redirect_uri** - Should be the same as the Redirect URI defined in your [API dashboard](https://coins.ph/user/api) page.\n\nA common example of a url for requesting user permission is as follows:\n\n```\nhttps://coins.ph/user/api/authorize?client_id=yourclientid&response_type=token&redirect_uri=example.com\n```\n\nOnce a user approves your application, the user will be redirected to the `redirect_uri` defined in the [API dashboard](https://coins.ph/user/api). The `redirect_uri` will then contain the following parameters appended to the url:\n\n* **access_token** - The token to be attached to each request to prove authentication.\n* **token_type** - The type of token returned.\n* **state** - The scopes of the provided token.\n\nThe 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.\n\n### Server Side Flow\n\nThis 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.\n\n#### Access Token\n\nThe application server can retrieve an `access_token` for the user by doing a POST request to the `/user/oauthtoken` endpoint with the following parameters:\n\n* **client_id** - Select `show` on your chosen application's API Access dashboard. This is the API Key as displayed on the dialog.\n* **client_secret** - Select `show` on your chosen application's API Access dashboard. This is Secret as displayed on the dialog.\n* **code** - The `code` retrieved from the `redirect_uri`\n* **grant_type** - `authorization_code` is used to retrieve an access token.\n* **redirect_uri** - The `redirect_uri` as defined in your chosen application's API Access dashboard.\n\nUpon 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:\n\n```\nAuthorization: Bearer useraccesstoken\n```\n\n#### Refresh Token\n\nIn 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.\n\nUsing 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:\n\n* **client_id** - Select `show` on your chosen application's API Access dashboard. This is the API Key as displayed on the dialog.\n* **client_secret** - Select `show` on your chosen application's API Access dashboard. This is Secret as displayed on the dialog.\n* **refresh_token** - The `refresh_token` retrieved from the previous POST request to `/user/oauthtoken`.\n* **grant_type** - `refresh_token` is used to use the `refresh_token` to retrieve a new access token.\n* **redirect_uri** - The `redirect_uri` as defined in your chosen application's API Access dashboard.\n\nUpon receiving the new `access_token`, API requests can proceed as normal by including the `access_token` in the `Authorization` header.\n\n```\nAuthorization: Bearer useraccesstoken\n```\n\n#### Server Side Flow Example\n\nExample of a common server-side flow:\n\n1. Direct the user to `https://coins.ph/user/api/authorize?client_id=yourclientid&response_type=code&grant_type=authorization_code`\n2. User selects \"Allow\"\n3. User is redirected to `http://yourredirecturl.com#code=somecode`\n4. Client application retrieves the token from the url and sends it to the application server.\n5. Application server initiates a `POST` request to https://coins.ph/user/oauthtoken with an HTTP Content-Type header of `application/x-www-form-urlencoded`\n6. The oauthtoken endpoint responds with a json that contains the key `access_token`\n7. Application server stores this token in behalf of the user.\n8. The application server can now initiate API calls in behalf of the user, with the header `Authorization: Bearer useraccesstoken` for each API call.\n\n### Client Side Flow\n\nThis 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:\n\n```\nAuthorization: Bearer youraccesstoken\n```\n\n#### Client Side Flow Example\n\nExample of a common client-side flow:\n\n1. Direct the user to `https://coins.ph/user/api/authorize?client_id=yourclientid&response_type=token`\n2. User selects \"Allow\"\n3. User is redirected to `http://yourredirecturl.com#access_token=someaccesstoken&token_type=Bearer&state=&scope=buyorder+sellorder+history`\n4. Client application retrieves the token from the url\n5. Client application can now initiate an API call, with the header `Authorization: Bearer someaccesstoken` for each API call.\n\n## Initiating API calls with OAuth2\n\nOnce the user or your application server has the `access_token` an API call can\nbe made with the following required HTTP headers:\n\n* Authorization - Authorization type followed by the access token ie. `Bearer token`\n* nonce - A number that can only be used once per user.","excerpt":"","slug":"oauth","type":"basic","title":"OAuth2"}
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](https://coins.ph/user/api) you can get the necessary OAuth2 tokens to configure your application and begin using our API. > 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 `http://coins.ph/user/api/authorize` with the following query parameters: * **client_id** - Select `show` on your chosen application's [API Access](https://coins.ph/user/api) dashboard. This is the API Key as displayed on the dialog. * **response_type** - Can either be `token` or `code`. `token` is used for client-side flows, while `code` is used for server-side flows. * **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](https://coins.ph/user/api) 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](https://coins.ph/user/api) 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](https://coins.ph/user/api). 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. * **state** - The scopes of the provided token. 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 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 the `redirect_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 the `refresh_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: 1. Direct the user to `https://coins.ph/user/api/authorize?client_id=yourclientid&response_type=code&grant_type=authorization_code` 2. User selects "Allow" 3. User is redirected to `http://yourredirecturl.com#code=somecode` 4. Client application retrieves the token from the url and sends it to the application server. 5. Application server initiates a `POST` request to https://coins.ph/user/oauthtoken with an HTTP Content-Type header of `application/x-www-form-urlencoded` 6. The oauthtoken endpoint responds with a json that contains the key `access_token` 7. Application server stores this token in behalf of the user. 8. 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 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: 1. Direct the user to `https://coins.ph/user/api/authorize?client_id=yourclientid&response_type=token` 2. User selects "Allow" 3. User is redirected to `http://yourredirecturl.com#access_token=someaccesstoken&token_type=Bearer&state=&scope=buyorder+sellorder+history` 4. Client application retrieves the token from the url 5. 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.