Obtaining an Access Token

The GoCoin API uses OAuth 2.0 for authentication. All requests to the API require an access token. There are two ways to obtain an access token:

  1. Obtain an API Key from the GoCoin Dashboard (Easy)
  2. Authorization Code Request (Advanced)

Both of these methods use the authorization_code OAuth grant type. Our Authorization Code Tokens are long-lived - they will not expire unless they are revoked manually from the dashboard.

Note: A user can only have a single access_token at a time per application - obtaining a second access token will invalidate the first.

To further understand the OAuth 2.0, please review the following:

Scopes

Scopes define the access privileges for an authorization & token. A full list of available scopes can be found here.

Obtaining an API Key

An API Key is a 'pre-scoped access token.' A step by step walkthrough on obtaining an API key is available here

It is an access token with the scope "user_read invoice_read_write." If this access token were to be compromised, an attacker could only get user information and create invoices.

Note: A user can only have a single API key at a time - obtaining a second API key will invalidate the first.

This method is geared towards users who:
* are non-technical * are using a plugin * have a single web property or application * have short development cycles and need to integrate quickly

Authorization_Code Request

A full example is available here
You will need the your application's ID & Secret Key to proceed.

This process should occur in the admin panel of the application.

3rd party apps should authorize their users with an authorization_code grant type. Tokens are long-lived (but can be revoked from the gocoin dashboard).

Initially, the app should open this address in a browser (redirect_uri must match given app) - note that this request is routed to the GoCoin dashboard, not the api, located at https://dashboard.gocoin.com

https://dashboard.gocoin.com/auth?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=user_read&state=OPTIONAL

You will, be asked to Authorize the application you created. Verify that the scope shown is the scope you requested, and click 'Allow'

*Note: If you click deny, you will be redirected to the page with an error message. More information is available in the spec

After allowing the app to access your account, you will be redirected to the value set as the redirect_uri

https://YOUR_REDIRECT_URI?code=123987239817239187239187231231231231&state=OPTIONAL

If you get an error for 'invalid redirect_uri' please check your request and make sure that what is being passed is an EXACT match to what was set during application set up.

The state parameter should be checked to match the one that was in the initial url marked 'OPTIONAL' above.

If the state is valid, you should make a request for an access token using the 'code' in the querystring.

Example Request using authorization_code grant
POST /oauth/token HTTP/1.1
Host: https://api.gocoin.com
Content-Type: application/json
Cache-Control: no-cache

{
 "grant_type"    : "authorization_code",
 "code"          : "efsdSDASDlkfjoeiwjwekfmwemfwbvlbwi4d",
 "client_id"     : "676YDu5PS2hR8jbGhH2NSpsfGp7swUkWVWhRJnE5SwJKn2dePdE5rkNUwdve5qYw",
 "client_secret" : "rSMPwVhf2DXvcYh55bEh2exxVThWFgsnMZcyNjMNN8ShcMzab9smcxVrGbvwU9Ex",
 "redirect_uri"  : "http://etc.com"
}

The request above will return an access token. It is a bearer token. Responses from both requests above will look like this:

{
    "access_token": "68f77b685e710b023afc641c6b9e4f161f67d2eb4b40bd4147598d2efe442750",
    "token_type": "bearer",
    "scope": "user_read_write"
}

Next: Storing and Using your Access Token

Recent Discussions

19 Feb, 2017 11:23 PM
16 Feb, 2017 05:18 PM
16 Feb, 2017 12:34 PM
16 Feb, 2017 08:18 AM
16 Feb, 2017 06:51 AM