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 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
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>
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`
**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
"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: