# 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.

{% hint style="info" %}
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.
{% endhint %}

## 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`.

{% stepper %}
{% step %}

#### 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`. |

{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}

{% content-ref url="/pages/CwpN0JJlaofAWIFORUfe" %}
[API Reference](/api-references/api-guides/authentication/oauth-service/api-reference.md)
{% endcontent-ref %}

**Example request:**

```bash
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.
{% endstep %}

{% step %}

#### 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:**

```json
{
  "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}}
```

{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.emporix.io/api-references/api-guides/authentication/oauth-service/oauth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.