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:

* [Full OAuth 2.0 Spec](


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

This method is geared to more complex integrations with the GoCoin API. This functionality is only available through GoCoin's legacy dashboard <> for the time being.

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 <>



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`




**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


Content-Type: application/json

Cache-Control: no-cache


 "grant_type"    : "authorization_code",

 "code"          : "efsdSDASDlkfjoeiwjwekfmwemfwbvlbwi4d",

 "client_id"     : "676YDu5PS2hR8jbGhH2NSpsfGp7swUkWVWhRJnE5SwJKn2dePdE5rkNUwdve5qYw",

 "client_secret" : "rSMPwVhf2DXvcYh55bEh2exxVThWFgsnMZcyNjMNN8ShcMzab9smcxVrGbvwU9Ex",

 "redirect_uri"  : ""



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"