Developer : Authentication

Manage applications

Before your application can use the Goodsie API a user must first grant it access. Goodsie uses OAuth 2.0 to handle authentication and authorization. If you've built apps for Twitter or Facebook you may be familiar with OAuth 2.0. This section gives a brief overview of how OAuth 2.0 works in the context of the Goodsie API.

To start you should register your application to obtain a client ID and secret. These credentials should be kept secret; your application will use them every time it requests access to a new user's Goodsie store.

The basic process is this:

  • When your application initially needs access to a user's Goodsie store it must obtain an authorization code. This is a short-lived token that can only be used to request a longer-lived access token that you will use to make API requests on the user's behalf. To get an authorization code your application redirects your user's browser to the Goodsie Authorize page where the user will be able to choose whether to grant access to your application or not.
  • If the user decides to grant your application access to Goodsie his or her browser is redirected back to your application with a code=THE_AUTHORIZATION_CODE query parameter in the URL. Your application parses this short-lived code out of the URL and exchanges it for a longer-lived access token.
  • To obtain the access token your application POSTs the authorization code along with its client credentials to Goodsie. If the authorization code and client credentials are correct Goodsie responds with a JSON result containing the token value. Your application stores this securely.
  • To access the Goodsie API your application supplies the access token in the HTTP header or URL query string when making an HTTPS request to Goodsie.

A more in-depth explanation of the authorization flow follows.

Obtaining an authorization code

To begin the authentication process you direct the user's browser to the Goodsie authorization page (https://goodsie.com/oauth2/authorize). You must pass along several required parameters in the query string:

Parameter Description
client_id The application's client ID/key
response_type code to indicate a request for an authorization code
redirect_uri The URI that the user will be redirected to after they grant or deny the application access
scope The requested access scope(s) separated by spaces (+ when url-encoded). See Access scopes for more details

 

For example:

https://goodsie.com/oauth2/authorize?
    client_id=YOUR_CLIENT_ID&response_type=code&
    scope=storefront+admin&
    redirect_uri=http://yourapp.com/goodsie/oauth-callback

The Goodsie authorization page asks the user to authorize your application. If the user is not signed in to Goodsie they will be prompted to sign in first. No matter what the user chooses they will be redirected back to the redirect_uri you provided. You can determine whether they authorized your application or not by inspecting the query string parameters.

If the user chose to grant your application access there will be a code parameter in the query string:

http://yourapp.com/goodsie/oauth-callback?
    code=aa647e14d93806787c0d5f62c91dc5

If the user declined to authorize your application there will be error and error_description parameters in the query string explaining what happened:

http://yourapp.com/goodsie/oauth-callback?
    error=access_denied&error_description=Access+denied

If the user declined to authorize then your application should handle the result gracefully. If the user authorized your application then it should immediately exchange the provided authorization code for an access token.

Obtaining an access token

To exchange a temporary authorization code for an access token your application must send a POST request to the Goodsie access token endpoint:

https://goodsie.com/oauth2/access_token

The POST body must contain the following parameters:

Parameter Description
client_id The application's client ID/key
client_secret The application's client secret
grant_type authorization_code to indicate that you are passing the authorization code obtained in the previous step
redirect_uri The same URI that you passed in the authorization request
code The authorization code obtained from the authorization result

 

An example curl call would look like:

curl "https://goodsie.com/oauth2/access_token" \
    -d 'client_id=YOUR_CLIENT_ID' \
    -d 'client_secret=YOUR_CLIENT_SECRET' \
    -d 'grant_type=authorization_code' \
    -d 'redirect_uri=http://yourapp.com/goodsie/oauth-callback' \
    -d 'code=aa647e14d93806787c0d5f62c91dc5'

This request will return a JSON result:

{
    "access_token": "5b3d4a9a09", 
    "expire_in": 315360000, 
    "refresh_token": "6452f809b1", 
    "scope": "storefront", 
    "token_type": "bearer"
}

Your application should securely store the access_token value. Any party that knows this token value will be able to make authenticated requests to Goodsie on behalf of the user. The scope property indicates which Access scopes the token has been authorized to access. Access tokens generated by Goodsie are effectively non-expiring so you can ignore the refresh_token and expire_in properties.

Your application may now make authenticated requests to the Goodsie API.

Client-side authorization flow

If your application has no back-end server with which to make the final token exchange (for example, it runs completely in JavaScript in the user's browser) you can use client-side authorization to obtain an access token directly. The process starts much like the server-side flow above with a request to https://goodsie.com/oauth2/authorize. Instead, however, you will specify a response_type with the value token:

https://goodsie.com/oauth2/authorize?
    client_id=YOUR_CLIENT_ID&response_type=token&
    scope=storefront+admin&
    redirect_uri=http://yourapp.com/goodsie/oauth-callback

When the user authorizes your application on Goodsie their browser will be redirected to redirect_uri. Rather than being passed an authorization code as in the server-side flow, Goodsie will include an access token in the URL hash fragment:

http://yourapp.com/goodsie/oauth-callback#access_token=THE_TOKEN...

Your client-side code can retrieve the token from the URL fragment and use it to make authenticated requests to the Goodsie API.

Making authenticated API requests

Once your application has obtained an access token it can access the Goodsie API on behalf of the user. The access token can be included in a request's HTTP headers or in the URL's query string. We recommend passing the access token as an HTTP header whenever possible.

Passing the token as an HTTP header:

curl -H "Authorization: Bearer THE_TOKEN_VALUE" \
    https://goodsie.com/api/v1/store

Passing the token in the query string:

curl https://goodsie.com/api/v1/store?
    bearer_token=THE_TOKEN_VALUE

Access scopes

An access scope (or simply scope) is a range of functionality within the Goodsie API. When an access token is granted, it is granted access to one or more scopes. The Goodsie API currently has three available scopes:

Scope Description
storefront Read access to products, pages, and storefront metadata
cart (Currently unused) Read and write access to a Goodsie-hosted shopping cart from a third-party application
admin Write access to storefront-scoped resources as well as read and write access to administrator resources such as orders, coupons, shipping data, and tax data

 

The motivation behind multiple scopes is that Goodsie users may want to grant some access to an application (for example, to display a Goodsie store's products on an external site) without allowing the application to access administrator functionality such as customer orders.

If your application does not need to create products and pages or display private information such as customer orders and coupon codes it should generally only request storefront and cart scopes. Your application should only request the admin scope if it needs to act as a store administrator.