E-shop verification using OAuth
If you need to authenticate Shoptet administrators using their existing Shoptet credentials—for example, to save specific settings for an individual add-on installation—you can utilize the OAuth server functionality.
This authentication mechanism ensures that the user is indeed the legitimate e-shop administrator, eliminating the need to handle their passwords or manage authorization directly.
OAuth serves strictly as an identity verification method and does not support storing data (such as add-on settings). You must handle and store such data separately within your own data structure.
The procedure assumes that you have the e-shop ID (shopId) stored in your database of API access tokens. You must ensure you use the correct API access token corresponding to the given shopId.
The initial step in verifying a user and their associated e-shop involves obtaining the OAuth server URL against which the user's identity will be authenticated.
1. Obtaining the OAuth Server URL
Fill in your settings URL into Add-ons settings » "Description" tab » "Addon settings URL" field.
If you use the #SHOP_ID# placeholder in your URL, it will be replaced with the actual e-shop ID. For example, the URL https://www.my-server.com/shoptet/addons/my-addon/settings?eshopId=#SHOP_ID# becomes https://www.my-server.cz/shoptet/addons/my-addon/settings?eshopId=12345.
If you include the #LANGUAGE# placeholder in your URL, it will be replaced with the e-shop's current language. For example, https://www.my-server.com/shoptet/addons/my-addon/settings?language=#LANGUAGE# becomes https://www.my-server.com/shoptet/addons/my-addon/settings?language=cs.
From the received eshopId, find the corresponding API access token in your database and call the Eshop info endpoint. In the response, check the field data.urls[] and find the object with the ident value equal to oauth and use the value from the url field as the OAuth server URL for the user who was logged in.
Note that the domain may change over time. We recommend registering the eshop:projectDomain webhook so you can update the domain in your system as needed.
<?php
$baseOAuthUrl = current(array_filter($response['data']['urls'], function ($url) {
return $url['ident'] == 'oauth';
}, ARRAY_FILTER_USE_BOTH))['url'];
$baseOAuthUrl will be something like https://example.myshoptet.com/action/OAuthServer/
2. Obtaining the OAuth code (one-time code)
Shoptet supports two methods for obtaining the OAuth code:
- Full OAuth with redirect: Redirecting users to Shoptet (recommended if you need to authenticate the Shoptet administrator directly on your website).
- Simplified OAuth: The OAuth code is provided directly, for example, within an iframe URL.
2.1 Full OAuth with redirect
Redirect the e-shop user to the OAuth server for authentication.
Save the generated URL for the current user (e.g., in the user's session), as you will need this value in the next step.
$_SESSION['base_oauth_url'] = $baseOAuthUrl;
Construct the URL to which the user will be redirected.
// $_SESSION['base_oauth_url'] contains the ending slash
$url = $_SESSION['base_oauth_url'] . 'authorize';
Add GET parameters to the URL:
/ Your client id in OAuth server
// This is an example only, the specific value can be found in
// the e-shop administration -> Link -> API partner -> Access to API
$param['client_id'] = 'wae54...slekn';
// authorization group in OAuth server, enter 'basic_eshop'
$param['scope'] = 'basic_eshop';
To increase the security, add state parameter.
$state = uniqid();
$_SESSION["state"] = $state;
$param['state'] = $state;
The state parameter is optional but strongly recommended, as it provides protection against XSRF attacks. Generate a unique state value, store it for the current user, and include it in the request to the OAuth server. The OAuth server will return this parameter unchanged in its response, allowing you to verify the authenticity of the request (see the verification step below).
Next, add the response_type and redirect_uri parameters to your request URL.
// response_type is always 'code'
$param['response_type'] = 'code';
// returning url (to your server), to which the OAuth server redirects the user after sucessful verification
// redirect_uri must be entered in addon settins as "URL for user authorization".
// The OAuth server inspects whether the addresses are matching;
// if the address entered in administration does not match with address sent,
// the OAuth server responds with error
$param['redirect_uri'] = 'https://www.my-server.com/shoptet/addon/my-addon/code';
// Then create the url and redirect the user to OAuth server
$url = $url . "?" . http_build_query($param);
header("Location: " . $url);
The OAuth server authenticates the user and redirects them back to your specified redirect_uri.
In the redirected GET request, you'll receive the code parameter, and optionally, the state parameter you previously provided.
$code = $_GET['code'];
$state = $_GET['state'];
// Check state parameters. When the values are different, someone other than you
// initiated the request and your code should not continue.
if ($state != $_SESSION['state]) {
die('State parameters do not match');
}
2.2 Simplified OAuth
In this case, you obtain the OAuth code directly from the URL, typically from GET parameters (depending on where you place the #OAUTH_CODE# placeholder). For example:
$code = $_GET['code'];
3. Getting the OAuth access token
The next step is to obtain the OAuth access token, which provides the identity of the user or e-shop.
This OAuth access token is different from the token you receive when installing the add-on.
The request is sent in the background, without the user’s knowledge.
$data = [
// $code is the value from the GET parameter
'code' => $code,
// grant_type is always 'authorization_code'
'grant_type' => 'authorization_code',
// Your client id in OAuth server
// This is an example only, the specific value can be found in
// e-shop administration -> Link -> API partner -> Access to API
'client_id' => '<your client id>',
// Your secret string for communication with OAuth server.
// The specific value can be found in e-shop administration -> Link -> API partner -> Access to API.
// Contact Shoptet, if client_secret is not available (for older API partners, it was not generated automatically)
'client_secret' => '<your client secret>',
// redirect_uri must be entered in addon settings as "URL for user authorization".
// The OAuth server inspects whether the addresses are matching;
// if the address entered in administration does not match with address sent, the OAuth server responds with error
'redirect_uri' => 'https://www.my-server.com/shoptet/addon/my-addon/code',
// Enter 'basic_eshop'
'scope' => 'basic_eshop'
];
$url = $_SESSION['base_oauth_url'] . 'token';
Send a POST request:
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
die("CURL Error: " . $err);
}
The response will contain the access_token in JSON format:
{
"access_token": "90r3azmxy6dbxzpjfxj237cjt8rp0f4hq6uygone78i4n4zk47xb649pls1097fc0xs501hjhpv9tlj2k9hc6xhutymtthet8dzx0sm1ih7r6ml6gf6hc4dixqn48l0r5qk1ynqp0fvojief30b2f70rnedfcy2zyqhkin326ynvdv404hn1xw8nqct6rkn9h4xm9za2i53pbb8hqkmz37qdpol5yr3dciftn0vl04jfvpxg4l36lnw9vsqdyke",
"expires_in": 43200,
"token_type": "bearer",
"scope": "basic_eshop"
}
$response = json_decode($response, TRUE);
$accessToken = $response['access_token'];
4. Getting the e-shop’s identity
To obtain the e-shop’s identity, submit a request to the OAuth server with an authorization header containing the OAuth access token.
Construct the request URL:
$url = $_SESSION['base_oauth_url'] . 'resource?method=getBasicEshop';
Send the request:
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $accessToken]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
curl_close($curl);
A successful response will contain $response key success with value true.
{
"success":true,
"data": {
"user": {
"email": "novak@fenix.myshoptet.com",
"name": "Jan Novak"
},
"project": {
"id": 159834,
"url": "https://fenix.myshoptet.com/",
"name": "Fenix"
}
}
}
In $response in the data object is the id and url, which identifies the e-shop.
$response = json_decode($response, TRUE);
$_SESSION['project_id'] = $response['data']['project']['id'];
Getting the project_id gives you the linked current user of your pages with the e-shop administrator.
Error Identification
If an error occurs, the response will contain an error and error_description field:
{
"error": "You must use `client_secret`. Please contact us to obtain one.",
"error_description": null
}