OAuth: Overview

Eshopbox uses OAuth 2.0’s authorization code grant flow to issue access tokens on behalf of member of a workspace

  1. The member makes a request to install your app.

  2. Your app redirects to Eshopbox to load the OAuth grant screen and requests the required scopes.

  3. Eshopbox displays a prompt to receive authorization and prompts the user to login if required.

  4. The member consents to the scopes and is redirected to the redirect_uri.

  5. The app makes an access token request to Eshopbox including the client_id, client_secret, and code.

  6. Eshopbox returns the access token and requested scopes.

  7. The app uses the token to make requests to the Eshopbox API.

  8. Eshopbox returns the requested data.

Step 1: Get client credentials

You need to drop an email at support@eshopbox.com to obtain client_id & client_secret and get redirect_uri whitelisted.

Step 2: Ask for permission

After the user clicks the install link, Eshopbox displays a prompt to receive authorization from the user after login:

Login to Eshopbox

To show the prompt, redirect the user to the following URL with the query parameters defined below:

https://partners.myeshopbox.com/installation/authorize?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}&audience={audience}&response_type={response_type}
  • {client_id}: The API key for the app, provided by Eshopbox.

  • {scopes}: A comma-separated list of scopes.

  • {redirect_uri}: The URL to which a member is redirected after authorizing the client. The complete URL specified here must be added to your app as a whitelisted redirection URL.

  • {nonce}: A randomly selected value provided by your app that is unique for each authorization request. During the OAuth callback, your app must check that this value matches the one you provided during authorization. This mechanism is important for the security of your app.

  • {audience}: The unique identifier of the target API you want to access. Use https://wms.myeshopbox.com here.

  • {response_type}: Indicates which OAuth flow you want to perform. Use code for Authorization code Grant Flow.

Step 3: Confirm installation

When the user clicks the Install(Authorize App) button in the prompt, they’re redirected to the client server as specified above. The authorization_code is passed in the confirmation redirect.

https://example.org/some/redirect/uri?code={authorization_code}&state={nonce}

Before you continue, make sure your app performs the following security check. If checks fails, your app must reject the request with an error, and must not continue.

  • The nonce is the same one that your app provided to Eshopbox during step two.

If all security checks pass, then you can exchange the authorization_code for a permanent access token by sending a request to the /oauth/token endpoint:

POST https://partners.myeshopbox.com/api/v1/token

In your request, the following parameters must be provided in the request body:

  • client_id: The API key for the app, as defined in the step 1

  • client_secret: The API secret key for the app, as defined in the step 2

  • grant_type: Denotes the flow you are using. Use authorization_code for Authorization Code.

  • code: The authorization code provided in the redirect.

  • redirect_uri: The URL to which a user is redirected after authorizing the client(Step 2). The complete URL specified here must be added to your app as a whitelisted redirection URL.

The server responds with an access token:

{
"access_token": "eyJhbGciOiJSUzI1N...InR5cCI6IkpXVCIsI",
"refresh_token": "eyyRwffpgDlOyAxcv...OkguyrSHtteckIyueW",
"scope": "openid profile offline_access",
"expires_in": 86400,
"token_type": "Bearer"
}

The following values are returned:

  • access_token: An API access token you will use for subsequent authenticated requests to the API. Your app should store the token somewhere to make authenticated requests.

  • refresh_token: A Refresh Token is a special kind of token that can be used to obtain a renewed access token. You are able to request new access tokens until the Refresh Token is blacklisted. It’s important that refresh tokens are stored securely by the application because they essentially allow a user to remain authenticated forever.

    For native applications, refresh tokens improve the authentication experience significantly. The user has to authenticate only once, through the web authentication process. Subsequent re-authentication can take place without user interaction, using the Refresh Token.

  • scope: The list of access scopes that were granted to the application and are associated with the access token.

  • expires_in: The number of seconds until the access token expires.

  • token_type: The access token type provides the client with the information required to successfully utilize the access token to make a protected resource request (along with type-specific attributes). Right now this will only be Bearer.

Step 4: Making authenticated requests

After your app has obtained an API access token, it can make authenticated requests to the REST API. These requests are accompanied with a header Authorization: Bearer {access_token} where {access_token} is replaced with the permanent token.

Refresh(Regenerate) Access Token

To exchange the Refresh Token you received during authorization for a new Access Token, make a POST request to the /oauth/token endpoint in the Authentication API, using grant_type=refresh_token:

POST https://partners.myeshopbox.com/api/v1/token

In your request, the following parameters must be provided in the request body:

  • client_id: The API key for the app, as defined in the step 1

  • client_secret: The API secret key for the app, as defined in the step 1

  • grant_type: The type of grant to execute. Use refresh_token to refresh a token.

  • refresh_token: The Refresh Token to use.

The server responds with an access token:

{
"access_token": "eyJhbGciOiJSUzI1N...InR5cCI6IkpXVCIsI",
"id_token": "eyyRwffpgDlOyAxcv...OkguyrSHtteckIyueW",
"scope": "openid profile offline_access",
"expires_in": 86400,
"token_type": "Bearer"
}

The following values are returned:

  • access_token: An API access token you will use for subsequent authenticated requests to the API. Your app should store the token somewhere to make authenticated requests.

  • id_token: An ID Token is used in token-based authentication to cache user profile information and provide it to your app thereby providing better performance and experience. The application receives an ID Token after a user successfully authenticates, then consumes the ID Token and extracts user information from it, which it can then use to personalize the user's experience.

  • scope: The list of access scopes that were granted to the application and are associated with the access token. For example, scope=openid,profile.

  • expires_in: The number of seconds until the access token expires.

  • token_type: The access token type provides the client with the information required to successfully utilize the access token to make a protected resource request (along with type-specific attributes). Right now this will only be Bearer.