OAuth is a widely adopted authorization framework that allows you to consent to an App interacting with another on your behalf without having to reveal Merchant's sensitive data, such as passwords.

If you're building integrations that require access to Salla on behalf of other Salla Merchants, you should utilize OAuth 2.0 Protocol for Salla. You can use OAuth in gaining access to Merchants' stores with either Easy Mode or Custom Mode, using access tokens via the Apps built on Salla Partners Portal, which will be published on
Salla App Store.

:::check[]
Salla OAuth Format
All calls to the Merchant Public APIs require an Authorization header in this format:
Authorization: Bearer <ACCESS_TOKEN>
:::

What You will Need Before You Start:

Salla OAuth Benefits

Salla’s OAuth2.0 Flow

The OAuth 2.0 authorization flow is the initial step in installing an App on the Salla platform. By requiring the merchant to grant permission for the App to access their data within specific scope, this process helps to ensure that the store's data is safe and private. The OAuth 2.0 authorization procedure can be started by one of the following URLs:

The authorization Flow

The OAuth 2.0 authentication flow for installing an App on a Salla Store includes crucial URLs and endpoints that enable permission granting, code-to-token exchange, redirection, and token refreshing. The process involves the merchant's redirection to the Salla Authorization Server, login, granting permission, and obtaining an access token for API requests and accessing store data.

The following table summarize these and endpoints:

:::tip[]
To use the Authorization Endpoint https://accounts.salla.sa/oauth2/auth in your code, you will typically need to make an HTTP request to that URL.
:::

In addition to the base URLs mentioned above, OAuth 2.0 also uses query parameters to pass information during the authentication process. These query parameters serve different purposes and are included in the URLs when making requests to the authorization and token endpoints. Here are some common query parameters used in OAuth 2.0:

The installation URL

On the other hand, the installation URL allows for the immediate installation of the App to the merchant store. Unlike the typical authorization URL, the installation URL simplifies the app installation process by providing a direct URL with the app-id as a parameter. This URL can be used to initiate the app installation process. When the merchant clicks on the installation URL, the App will be automatically installed into their Salla Store.

The following diagram explains the flow of OAuth 2.0 in Salla, which will eventually result in access token generation.

Types of OAuth 2.0 in Salla

On Salla Partners Portal, and when you are creating your App, inside the App page details within the App Keys section, you will be provided with two methods for the OAuth protocol:

• Easy Mode, which is a simplified version of the protocol that requires minimal setup.
• Custom Mode, which allows for more advanced, manual configuration and the use of callback URLs.

Easy Mode (Recommended)

One of the foremost options of authorization via OAuth 2.0 in Salla Partners is Easy Mode Authorization. Utilizing Salla’s easy mode option, you can get the “access token” in one step automatically. It allows you to listen to the event, app.store.authorize, and then the process of generating the “access token” will be handled automatically at Salla‘s side back to you via the Webhook URL specified in the Webhooks/Notificationsyour of your App.

By selecting the Easy Mode Authorization option, Salla will handle everything, including extracting the authorization code and providing the client id and secret key together with the auth code to generate an access token. In the end, you will receive all of the above data in the form of a payload that contains a new access token generated for you, as the life validity of access tokens with Salla is 2 weeks.

The payload you will be receiving should look something like this:

{
  "event": "app.store.authorize",
  "merchant": 1234918345,
  "created_at": "2021-10-05 16:41:07",
  "data": {
    "access_token": "kG7eCGY0QlrgNZK1zFQmRIifReqsKJ9GJquPvsnJhho.l5Msr8jD5GBxxxx",
    "expires": 1634661667,
    "refresh_token": "WYQz6bMeaonMZ6WjhrkMTRb7fSkrAVpLH5n1V0_X9eU.e5Gqz1ks8Q8dHxxxx",
    "scope": "settings.read offline_access",
    "token_type": "bearer"
  }
}

:::tip[App Update]
In the easy mode, when the Merchant updates the app, Salla sends you the app.updated event. After that, Salla sends you the app store.authorized event, which provides you with the new access token and refresh token. This information will be delivered to you via webhook. Accordingly, you are required to update the access token and refresh token in your database.
:::

:::warning
The expires variable is returned as a unix timestamp value for the app event app.store.authorize.
:::

Custom Mode

When implementing an OAuth flow or any other third-party API that needs to redirect to the App after authentication or authorization, a callback URL should be set. The App will use this URL to reroute back to the App after the login and App scopes' permission procedures are finished. This cycle of authentication is called Custom Mode authentication.

Custom Mode Use Cases:

There are two steps that we need to follow in order to successfully set up a Custom Mode OAuth in Salla:

1. User Authorization

A Merchant has to authorize your App, with the set of App scopes, to be able to proceed with the process of obtaining the access token. Direct the Merchant to the callback URL you used while setting up your App on Salla Partner Portal. If this is the first time that you are requesting authorization from a Merchant, the merchant will be asked to log in to his/her Salla Store.

To obtain the access token for your App, the Merchant needs to authorize it with the App scopes.
Once the Merchant has logged in to their Salla Store account, they will be prompted by Salla to authorize access to your App. The merchant will be asked to grant authorization for your App to access their store data with the defined scopes.

If the access has been authorized, the user will be redirected to the Callback URL with the authorization code in the code query parameter, which you can fetch to continue the process of obtaining the access token:

2. Access Token Generation

When the Merchant authorizes the App, Salla returns the Merchant to your Callback URL with a code parameter containing an authorization code. Use the code in your access token request, which is a POST request with the required parameters to the token endpoint.

{
    "access_token": "ory_at_xqk9wODumvYyX8pIJVR-K2awBTsgE2IRZvRDOCHZ03Y.fkxXqRAmLEY_vZZnqD-iY67pvoZvPurYxEm-SoFl9MM",
    "expires": 1209599,
    "refresh_token": "ory_rt_nXjleNBPjVvTvch3SGJwtv28HOTX6FetRewPSrNJkq0.-M1SGikK7r4or6RjdiH_agZZBp22mW8EGdOZh-PUsRM",
    "scope": "settings.read customers.read_write orders.read_write carts.read branches.read_write categories.read_write brands.read_write products.read_write webhooks.read_write payments.read taxes.read_write specialoffers.read_write shippings.read_write marketing.read_write metadata.read_write offline_access",
    "token_type": "bearer"
}

Body Definition

The following enlists the values that are sent to the User Authorization endpoint to generate an access token:

{
    "access_token": "ory_at_xqk9wODumvYyX8pIJVR-K2awBTsgE2IRZvRDOCHZ03Y.fkxXqRAmLEY_vZZnqD-iY67pvoZvPurYxEm-SoFl9MM",
    "expires_in": 1209599, //this is returned as `seconds` timestamp value
    "refresh_token": "ory_rt_nXjleNBPjVvTvch3SGJxxxx",
    "scope": "settings.read customers.read_write orders.read_write carts.read branches.read_write categories.read_write brands.read_write products.read_write webhooks.read_write payments.read taxes.read_write specialoffers.read_write shippings.read_write marketing.read_write metadata.read_write offline_access",
    "token_type": "bearer"
}