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](http://tools.ietf.org/html/rfc6749#section-4.1)

Scopes

Scopes define the access privileges for an authorization & token. A full list of available scopes can be found [here](http://help.gocoin.com/kb/api-authorization/oauth-scopes).



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](http://help.gocoin.com/kb/api-authorization/api-keys-from-the-gocoin-dashboard)


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 <https://dashboard.gocoin.com/> 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 <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](http://tools.ietf.org/html/rfc6749#section-4.1)


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"

}

@@@