Authorization
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:
URL | Description |
---|---|
Authorization Endpoint | https://accounts.salla.sa/oauth2/auth This URL initiates the process of obtaining the merchant's permission for the App to access their store data on Salla. |
Token Endpoint | https://accounts.salla.sa/oauth2/token After the merchant grants permission, the App exchanges the authorization code for an access token at this endpoint. |
Redirect URI | https://client-app.com/callback Once the authentication process is complete, the authorization server redirects the user's browser to the registered redirect URI. |
Refresh Token Endpoint | https://accounts.salla.sa/oauth2/token If a refresh token is granted, this endpoint allows the client to obtain a new access token when the current one expires. |
User Info Endpoint | https://accounts.salla.sa/oauth2/user/info Once the authentication process is completed successfully, the Merchant details can be received via this endpoint. |
:::tip[]
To use the Authorization Endpoint
:::
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:
Query Parameter | Description | Example |
---|---|---|
client_id |
Identifies the client application making the request, which values can be fetched from your application on the Salla Partners Portal. | 1311508470xxx |
client_secret |
Identifies the client application making the request, which values can be fetched from your application on the Salla Partners Portal. | 362985662xxx |
response_type |
Specifies the desired response type from the authorization server. | code |
redirect_uri |
Indicates the URI for user redirection after completing the authorization process. | |
scope |
Specifies the requested permissions or access levels. | offline_access |
state |
Used to maintain state between the authorization request and the callback to prevent cross-site request forgery attacks. | 1234xxxx |
code |
The authorization code returned by the authorization endpoint. | xxxxxxxx |
grant_type |
Specifies the type of grant being used to authenticate the client. | authorization_code |
Including the client ID as a query parameter
It is common practice to include the client ID as a query parameter in the authorization URL for OAuth 2.0 authentication. This inclusion allows the authorization server to associate the authentication request with the specific client, ensuring client identification and authentication during the process. Here's an example of how the client ID can be included in the authorization URL:
In the example above, client_id=your_client_id
is appended to the authorization URL, where your_client_id should be replaced with the actual client ID issued by the authorization server.
:::check[]
Including the client ID as a query parameter in the authorization URL ensures authentication and identification of the client during OAuth 2.0. If the App has been previously approved, scope approval steps may be skipped, streamlining the process.
:::
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"
}
}
:::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.
Easily run the request straight from Postman by providing the required data to generate an access token
:::warning
Easy Mode is the only way allowed for published apps on the Salla App Store. Since Postman uses custom mode, you can implement that in your app for testing purposes only.
:::
{
"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:
:::warning[Important Notes]
✅ Access tokens expire after 2 weeks (14 days).
✅ If you want to generate the refresh token, set the scope value as offline_access
. E.G: scope = offline_access
.
✅ The expires
variable is returned as seconds
timestamp value
✅ Upon obtaining the access token, developers can utilize the User Info endpoint URL, https://accounts.salla.sa/oauth2/user/info
, to retrieve the Merchant details and store them alongside the access tokens.
:::
Refresh Access Token
A typical reason for refreshing a token is that the original access token has expired, which lasts for only 14 days (2 weeks). If you would like to request a new access token, you may do so by sending Salla's authorization server a token refresh request. A refresh token lasts for 1-month, and using it twice invalidates the access token that it was issued with.
Body Definition
The following enlists the values that are sent to the Token endpoint to Refreshing Access Tokens:
Easily run the request straight from Postman by providing the required data to generate an access token
{
"access_token": "ory_at_xqk9wODumvYyX8pIJVR-K2awBTsgE2IRZvRDOCHZ03Y.fkxXqRAmLEY_vZZnqD-iY67pvoZvPurYxEm-SoFl9MM",
"expires_in": 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"
}
:::warning[Important Notes]
✅ Refresh tokens expire after 1 month. The latest refresh token must always be used for the next refresh request.
✅ Using the refresh token twice will cause the OAuth server to invalidate your request for refreshing the access token, and that is due to security reasons.
✅ The expires
variable is returned as seconds
timestamp value
:::
Access Token Usage Example
Now you may use the access token to make requests, on behalf of the Merchant, from the resource server via the API (base endpoint url:
With the access token and the authroized App scopes to the App, you may start consuming any of Salla's API endpoints, such as fetching a list of brands
IP Whitelisting
IP whitelisting is a security feature that restricts access to an App to only the IP addresses that are included on the whitelist. This can be used to restrict unwanted access and protect critical data from potential compromise.
It works by denying all IP addresses, except for those specifically listed as "whitelisted," thereby limiting the access to only approved users. This way, developers can better protect their private data from potential outside threats, such as hackers and malware, by reducing the attack surface area.
IP Whitelisting can also be used for other purposes such as controlling bandwidth usage or limiting access to certain services. You may reach the App setup page by going to the Partners Dashboard and selecting the "My Apps" tab:
From this page, you can add the permitted IP addresses in the following area, which is labeled "App Trusted IPs":
:::note
Get additional information about App Trusted IPs by visiting this article.
:::
Open-Source Libraries
Salla developed various clients and OAuth-specific libraries, such as:
These open-source libraries, powered by Salla, are here to assist in bootstrapping your development journey with Salla by providing code snippets easily accessible, readable, and maintainable by Salla’s own experts as well as the Global Community of developers.