OAuth Tutorial

This tutorial explains how to obtain a service access token from the OAuth Service. A service access token is required in server-to-server calls in your backend, scripts or jobs to call Emporix APIs for tasks such as adding products, managing categories, or modifying prices.

Prerequisites

Before requesting a token, ensure you have:

• Client ID – Your application's client identifier
• Client secret – Your application's client secret

These data can be found in the Developer Portal.

If you want to grant only specific scopes for service access token, you can create dedicated credentials in the Developer Portal and assign the scopes you need. Then, in your request, use the Client ID and Secret credentials to obtain the limited access token.

Requesting a service access token

The OAuth Service uses the client credentials grant type, so you receive an access token by sending a request authenticating with your client ID and secret.

1

Send an authentication request

Send a POST request to the token endpoint with form-encoded credentials.

Endpoint: POST https://api.emporix.io/oauth/token

Headers:

Header	Value
Content-Type	application/x-www-form-urlencoded

Request body (form parameters):

Parameter	Description
grant_type	Always client_credentials for service access tokens
client_id	Your Client ID
client_secret	Your Client secret
scope	Optionally, specify a scope or several scopes that you want to grant to the user. For example, scope=category.category_manage category.category_publish category.category_read_unpublished category.category_unpublish. This limits access persmissions only to the specified functionalities. If the parameter is skipped, the user gets all scopes assigned to the client_id.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

Example request:

curl -i -X POST 'https://api.emporix.io/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id={{client_id}}' \
  -d 'client_secret={{client_secret}}' \
  -d 'grant_type=client_credentials' \
  -d 'scope=category.category_manage category.category_publish category.category_read_unpublished category.category_unpublish \

Replace {client_id} and {client_secret} with your actual values.

2

Use the response

A successful response returns a JSON object containing the access token and metadata:

Field	Description
access_token	The token to use in the Authorization header when calling Emporix APIs
token_type	Always Bearer
expires_in	Token lifetime in seconds (e.g. 14399)
session_idle_time	Session idle time in seconds
scope	The granted scope(s)
refresh_token	Empty for service access tokens (not supported)
refresh_token_expires_in	0 for service access tokens

Example response:

{
  "access_token": "vkFuQ6oTwj8_Ye4eiRSsqMeqLYNeQRJi",
  "token_type": "Bearer",
  "expires_in": 14399,
  "session_idle_time": 120,
  "refresh_token": "",
  "refresh_token_expires_in": 0,
  "scope": "scope=category.category_manage category.category_publish category.category_read_unpublished category.category_unpublish tenant=yourtenant"
}

Use the token in subsequent API calls by setting the Authorization header:

Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}

No refresh tokens: The OAuth Service does not support refresh tokens for service access tokens. When your token expires, send a new authentication request to POST /oauth/token to obtain a new access token.