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
- Supported Authorization Flows
- The Authorization Code flow
- The Client requests an authorization.
- The User is asked to authorize access within the scopes.
- The User is redirected back to your specified URI.
- The Client requests the access and refresh tokens using the received code.
- The Client receives the tokens.
- The Client uses the access token to make request to the Jumpseller API.
- The Client receives the API response.
- The Client requests new tokens when they are expired or revoked.
- The Client receives the new tokens.
- 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:
- The Client requests an authorization.
- The User is asked to authorize access within the scopes.
- The User is redirected back to your specified URI.
- The Client requests the access and refresh tokens using the received code.
- The Client receives the tokens.
- The Client uses the access token to make request to the Jumpseller API.
- The Client receives the API response.
- The Client requests new tokens when they are expired or revoked.
- 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:
Query Parameter | Description/Value |
---|---|
client_id | Required. The client ID of your registered application. |
redirect_uri | Required. The URI to redirect after user grants or denies authorization. |
response_type | Required. Set it to code. |
scope | Required. The whitespace-separated list of scopes necessary for your application. Check the list of scopes. |
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&scope=read_orders%20write_products%20read_customers%20write_promotions
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:
Query Parameter | Description/Value |
---|---|
client_id | Required. This is the client id of your OAuth 2 application. |
client_secret | Required. This is the client secret of your OAuth 2 application. |
grant_type | Required. This field must contain the value authorization_code. |
code | Required. The authorization code returned from the /authorize endpoint request. |
redirect_uri | Required. This is used only for validation and should be EXACTLY the same informed on the /oauth/authorize request. Use urn:ietf:wg:oauth:2.0:oob for testing from the terminal. |
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:
Key | Value |
---|---|
access_token | An access token that you can use requesting, for example, the Jumpseller API. |
token_type | The way the above access token should be used. Always is "bearer". |
expires_in | The period of time in seconds until your access token expires. |
refresh_token | This a token used to refresh/replace your access token when it is expired. |
created_at | The timestamp format of your |
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:
Parameter | Description/Value |
---|---|
client_id | Required. This is the client id of your OAuth 2 application. |
client_secret | Required. This is the client secret of your OAuth 2 application. |
grant_type | Required. This field must contain the value refresh_token. |
refresh_token | Required. The refresh token returned from authorization code exchange. |
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.