OAuth 2

OAuth 2 is the industry-standard protocol for authorization. Generally, OAuth provides to clients a secure delegated access to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials. Designed specifically to work with HTTP, OAuth essentially allows access tokens to be issued to third-party clients by an authorization server, with the approval of the resource owner. The third party then uses the access token to access the protected resources hosted by the resource server.

At Jumpseller, this authorization flow generates an access token in which you can use to request informations from the Jumpseller API.

Contents

1. Supported Authorization Flows
2. The Authorization Code flow
   1. The Client requests an authorization.
   2. The User is asked to authorize access within the scopes.
   3. The User is redirected back to your specified URI.
   4. The Client requests the access and refresh tokens using the received code.
   5. The Client receives the tokens.
   6. The Client uses the access token to make request to the Jumpseller API.
   7. The Client receives the API response.
   8. The Client requests new tokens when they are expired or revoked.
   9. The Client receives the new tokens.
3. Next steps

Supported Authorization Flows

The Jumpseller OAuth 2 service supports the Authorization Code flow, i.e., it uses your client id to request a code and then exchange this code for an access token and refresh token. By default the access token expires in 1 hour but you can get a new one with the refresh token.

The access token is used by the client to access the Jumpseller API.

The idea of refresh tokens is that if an access token is compromised, because it is short-lived, the attacker has a limited window in which to abuse it.

Refresh tokens, if compromised, are useless because the attacker requires the client id and secret in addition to the refresh token in order to gain an access token.

The Authorization Code flow

Among the different flows supported by OAuth 2, the Authorization Code Flow is the one used by Jumpseller. The majority of the programming languages already provides libraries that abstract OAuth 2 flow shown below and can make your work easier.

These are the steps for the authorization code flow:

1. The Client requests an authorization.
2. The User is asked to authorize access within the scopes.
3. The User is redirected back to your specified URI.
4. The Client requests the access and refresh tokens using the received code.
5. The Client receives the tokens.
6. The Client uses the access token to make request to the Jumpseller API.
7. The Client receives the API response.
8. The Client requests new tokens when they are expired or revoked.
9. The Client receives the new tokens.

Let's get started understanding all of them.

The Client requests an authorization

This step starts with the application requesting authorization to the Jumpseller OAuth 2 service:

GET https://accounts.jumpseller.com/oauth/authorize

This request must include the following parameters in the query string:

A typical request looks like this:

GET https://accounts.jumpseller.com/oauth/authorize?client_id=e27af9be9e7343dc29095d292d7a1103383a5d010c8912783e0fa54f993ca751&redirect_uri=http%3A%2F%2Flocalhost%3A8000%2Fcallback&response_type=code

The User is asked to authorize access within the scopes

After requesting the /oauth/authorize endpoint, the Jumpseller OAuth 2 service will present to the user details about the scopes for which access is being sought. The user then is asked to authorize access to the data sets defined in the scopes.

The User is redirected back to your specified URI

Regardless the authorization or denying by the user, the Jumpseller OAuth 2 service redirects back to the redirect_uri informed. From our example in step 1, this address is http://localhost:8000/callback.

If the user authorizes the request, the response query string will contain the code parameter. The code parameter is an authorization code that can be used in order to exchange for an access token and a refresh token. For example:

GET http://localhost:8000/callback?code=f04bb200f5779644a65e0a174f49776004bc3de060a96f961f72c5835533d006

The Client requests the access and refresh tokens using the received code

When you have the authorization code, you will need to make a POST request and exchange it with a access token. This POST request is done to the endpoint:

POST https://accounts.jumpseller.com/oauth/token

The body of this POST request must have the following parameters:

This is the cURL format to request your tokens using the code:

curl -F grant_type=authorization_code \
-F client_id=6e19c63534c711bd2ec82da2a4bcc80638c79223b6bad064ce81a8987ec49ecb \
-F client_secret=bfab60ff47504b29bf2a29c4a8f30800286a36b590b1c36ce619f5255f43b0ef \
-F code=f04bb200f5779644a65e0a174f49776004bc3de060a96f961f72c5835533d006 \
-F redirect_uri=urn:ietf:wg:oauth:2.0:oob \
-X POST https://accounts.jumpseller.com/oauth/token

The User receives the tokens

On success response for this request, the Jumpseller OAuth 2 service returns a 200 OK HTTP code in the response header and the following JSON data:

  {
    "access_token":"80de978742714f8747036188cf6bab538e976adf72144d545e185ae444bc473d",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"86454df3e89cd34bd006ac68a76f6f2af884822ed68ce417777a4cffaae64b61",
    "created_at":1502473092
  }

Let's understand each key-value:

We recommend storing this credentials into your App's database.

The Client uses the access token to make request to the Jumpseller API

With this access token you can start requesting the Jumpseller API. Let's make a simple GET request to the /store/info.json endpoint:

curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer 80de978742714f8747036188cf6bab538e976adf72144d545e185ae444bc473d" \
https://api.jumpseller.com/v1/store/info.json

The Client receives the API response

The response of this request returns the following JSON data:

  {
    "store": {
      "name":"Your Store",
      "code":"yourstore",
      "currency":"EUR",
      "country":"PT",
      "email":"youremail@example.com"
    }
  }

Go to the Jumpseller API page to know about our endpoints.

The Client requests new tokens when they are expired or revoked

The access token is valid for just 1 hour so when you are building your web application it is your responsibility to check if the current access token is expired and then use the refresh token to request a new access token.

OBS: Save the access and refresh tokens as well as an expiration date created from the expires_in key-value on your database. This way you can check if this is expired and then refresh it everytime it is needed.

To refresh your access token, you should POST request the following endpoint:

POST https://accounts.jumpseller.com/oauth/token

The body of this POST request must have the following parameters:

This is the cURL format to request your refreshed tokens:

curl -F grant_type=refresh_token \
-F client_id=6e19c63534c711bd2ec82da2a4bcc80638c79223b6bad064ce81a8987ec49ecb \
-F client_secret=bfab60ff47504b29bf2a29c4a8f30800286a36b590b1c36ce619f5255f43b0ef \
-F refresh_token=86454df3e89cd34bd006ac68a76f6f2af884822ed68ce417777a4cffaae64b61 \
-X POST https://accounts.jumpseller.com/oauth/token

The Client receives the new tokens

The response will have the same JSON structure from the step 5 but with brand new tokens.

Next steps

Now you understand the authorization code flow from OAuth 2, it is time to learn more about the Jumpseller API and use it with your access token.