Introduction

Allegro API introduces 4 methods of authorization and authentication:

  • Authorization Code flow - the most popular for the OAuth standard - it is used in situations where the client (application) needs to perform operations on behalf of the user,

  • Device flow - enables authorization on devices or in applications that do not have a graphical interface or a way to enter text,

  • Client_credentials flow - allows you to authorize the application without the user’s consent for its operation, intended for resources that allow access to public data, e.g. downloading a list of categories,

  • Dynamic Client Registration (DCR) - enables the creation of application instances in an automated manner - intended for applications where the user installs a copy of the software (e.g. an instance of a shop platform in his own infrastructure).

In this guide you will learn what they are and how to use them.

information Regardless of the authorization method, the application can run on a single key (Client_ID). Do not require the user of your application to register a new instance of the application.

Authorization Code flow

REST API provides the access authorization of the Authorization Code - the most popular for the OAuth standard. It is used in situations where the client (application) needs to perform operations on behalf of the user. In such case, it is necessary to obtain a consent from the user for such action. For this purpose, the user is redirected to Allegro.pl to log in and, after correct authentication, the application returns a code which should be passed to OAuth to obtain an access token operating for the user that is logged in.

information Protect your application against the use of authorization_code by malicious software. To do this, provide the optional parameters code_challenge and code_challenge_method using PKCE (Proof Key for Code Exchange) mechanism. You can find more information in this article.

Application registration

Before logging in the user (and thus obtaining permission for the application to perform requests on his behalf), you must register the application, thanks to which you will receive access data necessary for the operation of the software communicating with Allegro REST API.

information

Application registration will only be possible for active accounts with enabled two-step login.

To facilitate, in the test environment two-step login will not be required.

To use the Authorization Code flow, register a new application in the tool provided by us and enter the following data:

  • app name - it is displayed to users when they grant your app consent to access their account,

  • brief description (optional) - we will not display it to users of your app. This information is for you to make it easier to distinguish between various apps,

  • check the option “The application will have a browser access, which the user will use to log in to Allegro (e.g. an application on the server or an executable file)”,

  • redirect addresses (addresses of applications to which the authorization code will be sent).

In the form, you must also accept the REST API terms and conditions.

information You can have up to 5 registered application keys on one account at a time.

When you approve the form, you will receive access data that will allow you to use REST API resources: Client ID and Client Secret.

information You cannot change the type of registered application.

Client ID and Client Secret are needed for communication in the OAuth protocol which – in version 2.0 - is supported by Allegro REST API as a standard. Access tokens are compliant with the JWT.

In the Allegro REST API, there is a limit for tokens which you can generate in a specific time for one user. If you exceed this limit, we will return error HTTP: 429 Too Many Requests. This means that the operations from your application are abnormal - make sure you are not creating more tokens than the operations you are performing require. Once generated, a token for one user should be used until it expires, after that time, refresh your token.

information All resources necessary for authorization are available at https://allegro.pl. They are not available under the address for calling resources https://api.allegro.pl/.

User authorization

The entire process is as follows:

1. Provide a button/link in your application, e.g. Login to Allegro, which triggers a properly parameterized HTTP request to a resource that allows user authentication:

https://allegro.pl/auth/oauth/authorize?response_type=code&client_id=a21...6be&redirect_uri=http://exemplary.redirect.uri
parameter description required / optional
response_type Type of response (here: code) required
client_id Client ID (obtained upon application registration) required
redirect_uri Return address where the code is sent (it has to be the same as the one provided upon application registration) required
code_challenge_method Encryption method (code_challenge) optional
code_challenge Code for the PKCE mechanism optional
prompt Method of authenticating the user during the authorization process optional
state Additional data which will be passed back to application after authorization optional
scope Scopes determining the level of authorization to use the Allegro API. You can learn more in further part of the guide. optional
information You can use additional parameters in authorization process in form of any url parameters, that will be passed back in redirect_uri. OAuth specification recommends however using parameter state to pass information needed by application to restore it’s state after redirect.

PKCE

Protect your application against the use of authorization_code by malicious software. To do this, use PKCE (Proof Key for Code Exchange) mechanism. To use it, generate code_verifier by yourself - it should be a random string containing between 43 and 128 characters, which you will use in access token request (point 5).

Then in the authorization process, add two parameters:

  • code_challenge - code for the PKCE mechanism, its value depends on the encryption method, which you specify in the code_challenge_method,

  • code_challenge_method - code_challenge encryption method. It can take one of two values:

    • S256 - means that the code_challenge is encrypted (with SHA-256 algorithm) code_verifier. Use this value - it provides better safety due to the encryption used,

    • plain - means that the code_challenge value will be equal to the code_verifier value.

The value of code_challenge depends on the encryption method, which you specified for code_challenge_method:

  • for S256: code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)),

  • for plain: code_challenge = code_verifier.


Example HTTP requests for code_verifier = KnAijeNvdSeloYlVcOh3HRmgZX57wDeVHiwRFQKO2F9DdBI:

  • for code_challenge_method=S256:
https://allegro.pl/auth/oauth/authorize?response_type=code&client_id=a21...6be&redirect_uri=http://exemplary.redirect.uri&code_challenge_method=S256&code_challenge=a69se03ZmsPhTLYQKHpGUH7m5waf-U8D-5pTwFRgLI4
  • for code_challenge_method=plain:
https://allegro.pl/auth/oauth/authorize?response_type=code&client_id=a21...6be&redirect_uri=http://exemplary.redirect.uri&code_challenge_method=plain&code_challenge=KnAijeNvdSeloYlVcOh3HRmgZX57wDeVHiwRFQKO2F9DdBI

Parametr prompt

Another optional mechanism you can use is silent authentication. In the authorization process add a parameter prompt=none, e.g.:

https://allegro.pl/auth/oauth/authorize?response_type=code&client_id=a21...6be&redirect_uri=http://exemplary.redirect.uri&prompt=none

You can also show users the account confirmation screen during allegro authentication. We will show the screen if in the authorization process, you add a parameter prompt=confirm:

https://allegro.pl/auth/oauth/authorize?response_type=code&client_id=a21...6be&redirect_uri=http://exemplary.redirect.uri&prompt=confirm

confirm
2. By clicking on it, the user is redirected to the log in form on Allegro.pl:

step1


3. After correct authentication, the user is redirected to the page where he grants a consent for the application to perform operations/requests on his behalf:

step2


Remember that is worth to handle scenario in which user choose “Anuluj” (Cancel). In this case, add suitable message.

4. After granting such consent, the user returns to the application and the authorization code is returned to the address provided as redirect_uri.

The code is:

  • disposable,

  • valid for 10 seconds,

  • needed to obtain an access token.

http://exemplary.redirect.uri/?code=pOPEy9Tq94aEss540azzC7xL6nCJDWto

5. With a valid code the application requests a token performing an HTTP request using the POST method to: https://allegro.pl/auth/oauth/token, and attaching the Authorization header with relevant contents:

curl -X POST \
  'https://allegro.pl/auth/oauth/token?grant_type=authorization_code&code=pOPEy9Tq94aEss540azzC7xL6nCJDWto&redirect_uri=http://exemplary.redirect.uri'
  -H 'Authorization: Basic YTI...Hg=' 
parameter description required / optional
Authorization HTTP header: Authorization. Basic authorization, with the content saved as client_id:client_secret secret (data obtained upon application registration) as Base64. Remember to encode all client_id: client_secret data with the “:” sign between the values. required
https://allegro.pl/auth/oauth/token Allegro endpoint which enables to obtain an OAuth token OAuth required
grant_type Type of access needed to obtain a token (here: authorization_code) required
code Authorization code (obtained in step 4) required
redirect_uri Redirect address (it has to be the same as the one provided upon application registration) required
code_verifier Verification code for the needs of the PKCE mechanism optional
information If you used PKCE in the point 1, you do not need to provide the Authorization header and the code_verifier parameter is now required parameter. Provide the same value, as you specified earlier, e.g.:
curl -X POST \
  'https://allegro.pl/auth/oauth/token?grant_type=authorization_code&code=pOPEy9Tq94aEss540azzC7xL6nCJDWto&redirect_uri=http://exemplary.redirect.uri&code_verifier=KnAijeNvdSeloYlVcOh3HRmgZX57wDeVHiwRFQKO2F9DdBI'

6. After the correct request, a response is returned in the JSON format, containing e.g. an access token which can be used when calling REST API resources:

Sample response:

{
  "access_token":"eyJ...dUA",                  -- access token which enables to perform 
                                               operations on API resources on behalf of 
                                               a user that is logged in
  "token_type":"bearer",                       -- token type (in our case: bearer)
  "refresh_token":"eyJ...QEQ",                 -- single-use refresh token, that allows to
                                               extend the validity of user authorization 
                                               up to 3 months
  "expires_in":43199,                          -- validity time of access token 
                                               (in seconds; a token is valid for 12 hours)
  "scope":"allegro_api",                       -- scope of data/functionalities for which 
                                               the user authorised the application
  "allegro_api": true,                         -- flag which shows, that token was 
                                               generated for API purposes (no direct use)
  "jti":"2184f3be-f6de-4a66-bd8f-b11347d7ba80" -- JWT token identifier 
                                               (no direct application)
}


information In future, response can contain additional fields.

Example php code implementing Authorization Code type (without PKCE):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
<?php
 
define('CLIENT_ID', ''); // enter the Client_ID of the application
define('CLIENT_SECRET', ''); // enter the Client_Secret of the application
define('REDIRECT_URI', ''); // enter redirect_uri
define('AUTH_URL', 'https://allegro.pl/auth/oauth/authorize');
define('TOKEN_URL', 'https://allegro.pl/auth/oauth/token');
 

function getAuthorizationCode() {
    $authorization_redirect_url = AUTH_URL . "?response_type=code&client_id=" 
    . CLIENT_ID . "&redirect_uri=" . REDIRECT_URI;
    ?>
    <html>
    <body>
    <a href="<?php echo $authorization_redirect_url; ?>">Login to Allegro</a>
    </body>
    </html>
    <?php
}
 

function getCurl($headers, $content) {
    $ch = curl_init();
    curl_setopt_array($ch, array(
        CURLOPT_URL => TOKEN_URL,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $content
    ));
    return $ch;
}
 

function getAccessToken($authorization_code) {
    $authorization = base64_encode(CLIENT_ID.':'.CLIENT_SECRET);
    $authorization_code = urlencode($authorization_code);
    $headers = array("Authorization: Basic {$authorization}","Content-Type: application/x-www-form-urlencoded");
    $content = "grant_type=authorization_code&code=${authorization_code}&redirect_uri=" . REDIRECT_URI;
    $ch = getCurl($headers, $content);
    $tokenResult = curl_exec($ch);
    $resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
 
    if ($tokenResult === false || $resultCode !== 200) {
        exit ("Something went wrong $resultCode $tokenResult");
    }
    return json_decode($tokenResult)->access_token;
}
 

function main(){
    if ($_GET["code"]) {
        $access_token = getAccessToken($_GET["code"]);
        echo "access_token = ", $access_token;
    } else {    
        getAuthorizationCode();
    }
}
 

main();
 
?>

Device flow

Use device flow path for authorizing users on devices or in apps that do not have:

  • a graphic interface,

  • a browser,

  • or other simple mechanism for entering the text.

This authorization method involves implementation of RFC OAuth 2.0 Device Flow. For more information, please refer to:

Device application registration

To use Device flow, register the new application in the tool provided by us and enter the following data:

  • app name - it is displayed to users when they grant your app consent to access their account,

  • brief description (optional) - we will not display it to users of your app. This information is for you to make it easier to distinguish between various apps,

  • check the option The application will work in environment without access to the browser or keyboard (e.g. a console application or TV)”.

In the form, you must also accept the REST API terms and conditions.

information

Application registration will only be possible for active accounts with enabled two-step login.

To facilitate, in the test environment two-step login will not be required.

When you approve the form, you will receive access data that will allow you to use REST API resources: Client ID and Client Secret.

information You can have up to 5 registered application keys on one account at a time.

In the Allegro REST API, there is a limit for tokens which you can generate in a specific time for one user. If you exceed this limit, we will return error HTTP: 429 Too Many Requests. This means that the operations from your application are abnormal - make sure you are not creating more tokens than the operations you are performing require. Once generated, a token for one user should be used until it expires, after that time, refresh your token.

information You cannot change the type of registered application.

Device flow - user authorization

device_flow_shema

You will receive a user_code and a device_code to integrate with your app. A user provides the user_code you generated on a special site verification_uri as well as grants the app consent to access their data and process changes on their behalf. If you want to have “clickable” link (e.g. you want to send it by e-mail or present it in form of QR code) use verification_uri_complete In the meantime, your app sends a request to a dedicated endpoint using the device_code to receive e.g. an access token you can use to call REST API resources on behalf of the user.

The entire process is as follows:

1, 2. Call POST https://allegro.pl/auth/oauth/device to receive:

  • user_code, which you will transfer to the user along with the verification address,

  • device_code, which is necessary for receiving an access token.


information The validity period of device_code and user_code you can check in field expires_in.

information HTTP header: Authorization. It includes Basic-type authorization with content in the client_id:client_secret form (you received the data upon registration) encoded with Base64. Remember to encode all client_id:client_secret data including “:” between the values.

Sample request:

curl -X POST \
  'https://allegro.pl/auth/oauth/device' \
  -H 'Authorization: Basic {base64(client_id:client_secret)}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id={client_id}'
information In the request, in the content after client_id: client_secret you can pass an additional scope parameter after the & character (e.g. {client_id}: {client_secret}&scope=allegro:api:sale:offers:write%20allegro:api:orders:read) - these are the scopes that define the authorization level to use the Allegro API. You can learn more in further part of the guide.

Sample response:

{
        user_code: "cbt3zdu4g",                             -- user code - we recommend
                                                            you present the data as XXX XXX XXX.
                                                            This form is easier to rewrite.
        device_code: "645629715",                           -- application code - necessary for
                                                            receiving the access token
        expires_in: "3600"                                  -- number of seconds the codes are
                                                            valid
        interval: “5”,                                      -- required access (in seconds)
                                                            between authorization status queries.
                                                            If your calls are too frequent, you
                                                            will receive a HTTP 400 status
                                                            response with “slow_down” code.
        verification_uri: “https://allegro.pl/skojarz-aplikacje”,   
                                                            -- address for user verification
        verification_uri_complete: “https://allegro.pl/skojarz-aplikacje?code=cbt3zdu4g”
                                                            -- verification address for a user 
                                                            with a filled out user code
}

3, 4a, 5. Ask the user to open, using any device, the address you provide (verification_uri) and enter the user code (user_code).

information If you want to have “clickable” link (e.g. you want to send it by e-mail or present it in form of QR code) use verification_uri_complete.

When the user enters the correct code we will ask them to log on to Allegro and grant their consent to access their personal data. Once all the steps are taken correctly, we will present information about successful account authorization.

4b. At the same time, your app should start calling:

curl -X POST \
'https://allegro.pl/auth/oauth/token?grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code={device_code}' \
  -H 'Authorization: Basic base64(clientId:secret)

You can receive 5 types of responses:

  • HTTP 200 status - correct answer. You will receive the access token, that will help you access REST API resources. Another attempt of using the same device code will result in the 400 status response. Device_code may return a token only once.

Sample response:

{
  "access_token":"eyJ...dUA",
  "token_type":"bearer",
  "refresh_token":"eyJ...SDA",
  "expires_in":43199,
  "scope":"allegro_api",
  "allegro_api": true,
  "jti":"2184f3be-f6de-4a66-bd8f-b11347d7ba80"
}


information In future, response can contain additional fields.

  • HTTP 400 status with a code:
{
    "error":"authorization_pending"     -- it means that your app should continue
                                        to call the resource because użytkownik
                                        the code has not been entered yet. 
}

or

{
    "error":"slow_down"                 -- it means that your app is making
                                        the calls too often. Adjust the number 
                                        of calls to the value defined in
                                        the “interval” field.
}
  • HTTP 400 status with a code:
{
    "error":"access_denied"              -- means that the user has denied access to
                                         your application. Your application should 
                                         stop polling this resource.
}
  • Status HTTP 400 z kodem:
{
    "error": "Invalid device code" 		  -- means that the code device_code is invalid
                                        or has been used. In that case,
                                        the application should stop polling
                                        with this code and generate a new one.
}
  • Response with 400 status code but with different error means that device_code and user_code have expired, or there is an error in your query. Check that you are sending the correct values:

    • Client ID,
    • Client Secret,
    • Device_code.

Example php code implementing Device flow authentication:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
<?php
define('CLIENT_ID', ''); // enter Client_ID
define('CLIENT_SECRET', ''); // enter Client_Secret
define('CODE_URL', 'https://allegro.pl/auth/oauth/device');
define('TOKEN_URL', 'https://allegro.pl/auth/oauth/token');

function getCurl($url, $headers, $content) {
	$ch = curl_init();
	curl_setopt_array($ch, array(
		CURLOPT_URL => $url,
		CURLOPT_HTTPHEADER => $headers,
		CURLOPT_SSL_VERIFYPEER => false,
		CURLOPT_RETURNTRANSFER => true,
		CURLOPT_POST => true,
		CURLOPT_POSTFIELDS => $content
	));
	return $ch;
}


function getCode(){
    $authorization = base64_encode(CLIENT_ID.':'.CLIENT_SECRET);
	$headers = array("Authorization: Basic {$authorization}","Content-Type: application/x-www-form-urlencoded");
	$content = "client_id=" .CLIENT_ID;
    $ch = getCurl(CODE_URL, $headers, $content);
    $result = curl_exec($ch);
    $resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($result === false || $resultCode !== 200) {
        exit ("Something went wrong:  $resultCode $result");
    }
    return json_decode($result);
}


function getAccessToken($device_code) {
	$authorization = base64_encode(CLIENT_ID.':'.CLIENT_SECRET);
	$headers = array("Authorization: Basic {$authorization}","Content-Type: application/x-www-form-urlencoded");
	$content = "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=${device_code}";
	$ch = getCurl(TOKEN_URL, $headers, $content);
	$tokenResult = curl_exec($ch);
	curl_close($ch);
	return json_decode($tokenResult);
}


function main(){
    $result = getCode();
    echo "User, open this address in the browser: \n" . $result->verification_uri_complete ."\n";
    $accessToken = false;
    $interval = (int)$result->interval;
     do {
         sleep($interval);
         $device_code = $result->device_code;
         $resultAccessToken = getAccessToken($device_code);
          if (isset($resultAccessToken->error)) {
               if ($resultAccessToken->error == 'access_denied') {
                   break; 
              } elseif ($resultAccessToken->error == 'slow_down') {
                   $interval++; 
                }
            } else {
                $accessToken = $resultAccessToken->access_token;
                echo "access_token = ", $accessToken;
            }
        } while ($accessToken == false);

    }


main();

?>

Client_credentials flow

Oauth2 supports a path that allows you to authorize the application without any action taken by the user. As a result, you will get access to resources marked as “bearer-token-for-application” in the “Authorizations” section in documentation. These resources give access to public data, e.g. retrieving a list of categories, browsing through a list of offers, etc.

To use this authorization method, you need to register your application, the process is exactly the same as in Authorization Code flow or Device flow.

Application authorization

The entire process is as follows:

1. The application requests a token by calling POST in https://allegro.pl/auth/oauth/token and:

  • providing value for “grant_type=client_credentials” access type,
  • adding the Authorization in the Basic base64(client_id:client_secret) format.
information Remember to encode all “client_id:client_secret” data along with “:” between the values.
curl -X POST \
      'https://allegro.pl/auth/oauth/token?grant_type=client_credentials' \
      -H 'Authorization: Basic base64(clientId:secret)'


2. Once you send a correct request, you will receive a JSON response with an access token. Use it with REST API resources marked as “bearer-token-for-application” in the “Authorizations” section in documentation.

Sample response:

{
  "access_token":"eyJ...dUA",                  -- access token which enables to perform 
                                               operations on API resources on behalf of 
                                               a user that is logged in
  "token_type":"bearer",                       -- token type (in our case: bearer)
  "refresh_token":"eyJ...QEQ",                 -- single-use refresh token, that allows to
                                               extend the validity of user authorization 
                                               up to 3 months
  "expires_in":43199,                          -- validity time of access token 
                                               (in seconds; a token is valid for 12 hours)
  "scope":"allegro_api",                       -- scope of data/functionalities for which 
                                               the user authorised the application
  "allegro_api": true,                         -- flag which shows, that token was 
                                               generated for API purposes (no direct use)
  "jti":"2184f3be-f6de-4a66-bd8f-b11347d7ba80" -- JWT token identifier 
                                               (no direct application)
}


information In future, response can contain additional fields.

Example php code implementing client_credentials flow authentication:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<?php
define('CLIENT_ID', ''); // enter Client_ID
define('CLIENT_SECRET', ''); // enter Client_Secret
define('TOKEN_URL', 'https://allegro.pl/auth/oauth/token'); 
 
function getCurl($headers, $content) {
    $ch = curl_init();
    curl_setopt_array($ch, array(
        CURLOPT_URL => TOKEN_URL,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $content
    ));
    return $ch;
}
 

function getAccessToken() 
{
    $authorization = base64_encode(CLIENT_ID.':'.CLIENT_SECRET);
    $headers = array("Authorization: Basic {$authorization}","Content-Type: application/x-www-form-urlencoded");
    $content = "grant_type=client_credentials";
    $ch = getCurl($headers, $content);
    $tokenResult = curl_exec($ch);
    $resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($tokenResult === false || $resultCode !== 200) {
        exit ("Something went wrong $resultCode $tokenResult");
    }
    return json_decode($tokenResult)->access_token;
}
 

function main()
{
    echo "access_token = ", getAccessToken();
}
 

main();
?>

Dynamic Client Registration

DCR is an extension to the OAuth2 standard that allows you to create automatically an instance of your application. If the client installs a copy of your software directly (e.g. an instance of a store platform in their own infrastructure), this type of authorization is just for you. DCR ensures full security of data authorization, and at the same time does not force each client to manually generate separate access data (client ID and client secret).

DCR_graph

Registration of DCR applications

1. To use DCR authorization, your software must have a Software statement ID, which is a unique application identifier. To get it, contact us (contact form) and write why you need to use DCR.

As the application author, you will find your personal Software statement ID in the application list - Application templates (Szablony aplikacji) on the page Allegro application management (Zarządzanie aplikacjami Allegro).

DCR_template

DCR - user authorization

2. To use DCR, the user of your application must have an Allegro account. Ask the application user to generate a one-time code on the website Generate code (Wygeneruj kod).

The code is valid for 2 minutes, during this time the application user must enter it, e.g. in the process of installing your own instance of your application.

DCR_code1


DCR_code2


3a. When the application is installed at the client’s premises, the installer must call POST https://api.allegro.pl/register and pass:

  • code - user-generated one-time code in the previous step,

  • client_name - name of the application being installed:

    • must be unique - propose a unique name for this particular instance of the application on your own, e.g. your application name + user id + date,

    • must be between 3 and 50 characters long,

    • the application name cannot be changed. This means that e.g. when updating the application, the name must remain the same.

  • redirect_uris - application redirect URIs. We suggest that the client specifies the application domain during installation, e.g. my.shop.com and the installer would automatically create a full redirect URI address on that basis, e.g. https://my.shop.com/AllegroCallbackUrl.php.

  • software_statement_id - application ID obtained from Allegro, uniquely associating the application instance with your application.

Sample request:

curl -X POST \
‘https://api.allegro.pl/register’ \
-H ‘Accept: appication/json’ \
-H ‘Content-Type: application/json’
-d ‘
{
    "code": "PXGTQBZXE_sample",
    "client_name": "my.shop.com 12345678 23-07-2020",
    "redirect_uris": [
        "https://my.shop.com/AllegroCallbackUrl.php"
    ],
    "software_statement_id": "3b8cacc7-eeec-42f9-9f7f-f35090c3d616"
}’


3b. In response, the installed application will receive:

  • client_id and client_secret - access data that is unique within the installation. The application instance should use them during the authorization process (code_flow or device_flow),

  • client_name - name of the application being installed (in accordance with the request),

  • software_statement_id - application ID obtained from Allegro, uniquely associating the application instance with your application.

information

Make sure that the application instance keeps the generated access data and uses it in communication with Allegro REST API.

Client_secret value will not appear in the list Allegro application management (Zarządzanie aplikacjami Allegro).

Sample response as specified Dynamic Client Registration:

201 Created
Content-Type: application/json
{
    "client_id": "17a747e9b9f74f428ad0203a245e7373",
    "client_secret": "edSDERFsx43dSDJKFDKFJDKLSFJ4dsdsjdkIRIfffeEDfxc",
    "client_id_issued_at": 1594363740,
    "client_secret_expires_at": 0,
    "redirect_uris": [
        "https://my.shop.com/AllegroCallbackUrl.php"
    ],
    "grant_types": [
        "authorization_code",
        "implicit",
        "refresh_token",
        "client_credentials"
    ],
    "client_name": "my.shop.com 12345678 23-07-2020",
    "software_statement_id": "3b8cacc7-eeec-42f9-9f7f-f35090c3d616"
}

When generating access data, errors may occur:

  • 403 “Incorrect access code. Please generate a new code and try again.” - user provided incorrect one-time code during application installation;

  • 422 “The name of the application is already in use - please enter a different one.” - the submitted application name is not unique.

4. Authorize the user using the received client_id and client_secret. To do this, use the authorization type code_flow, or device_flow.

Scope in the Allegro API

Scopes define the level of authorization to use the Allegro API. Each scope is assigned a set of permissions that define:

  • a set of resources that can be accessed using scope,

  • a set of operations that can be performed in scope.

List of available scopes

Individual scopes provide access to perform a number of operations that are defined for them. Currently available in the Allegro API scopes are:

Scope Scope range Available operations
allegro:api:profile:read View Allegro account data - View account data such as: login, first name and last name, company name
- View additional email addresses
- View ratings and rating summary
allegro:api:profile:write Change Allegro account data - Add or remove additional email addresses
allegro:api:sale:offers:read View created and listed offers - View offer’s data
- View detailed offer’s data
- Access to offer event journal
- View Allegro platform’s products
- View Allegro platform’s compatibility tables
- View classified packages
- Offer fees preview
- View rebates and promotions
- View multi variant offers
allegro:api:sale:offers:write List and change offers - Add, change and delete offer
- List and delist offer
- Add offer assigned to product
- Create new products
- Change offers, prices and stock in bulk
- Add and remove multi variant offer sets
- Change, add and remove rebates and promotions
allegro:api:orders:read View orders - View orders
- Access order events journal
- View refund claims
- View parcels details, protocols, labels
allegro:api:orders:write Manage orders - Add tracking numbers
- Change order status
- Create and cancel refund claims
- Create and cancel parcels
allegro:api:ratings Manage user ratings - View user ratings
- Reply to rating messages
- Ask for rating change
allegro:api:disputes Manage disputes - View disputes, messages and attachmentsw
- Reply to messages and add attachments
allegro:api:bids Manage bid - Make bids
- View already made bids
allegro:api:billing:read View billing - View current balance and billing history
- View offer fees
allegro:api:payments:read View payments - View payment history
- View payment refunds
allegro:api:payments:write Refund a payment - Refund a payment
allegro:api:sale:settings:read View sale settings - View size tables
- View points of service
- View classified offer contacts
- View additional services
- View warranty, implied warranty and return policies
- View shipping rates
- View delivery settings
- View offer tags
- View user black list
allegro:api:sale:settings:write Change sale settings - Add, change and remove points of service
- Add and change classified offer contacts
- Define and change additional services
- Define and change return policy, warranty and implied warranty
- Define and change shipping rates
- Change delivery settings
- Add, edit and remove offer tags
- Add users to black list and remove users from black list
allegro:api:campaigns Manage campaigns - Apply for and manage promotional campaigns
- Apply for and manage badge campaigns


The scope value assigned to a given Allegro REST API resource you will find in the documentation.

Authorization using scope

So far, each of the applications registered on the Allegro Application Management website (Zarządzanie aplikacjami Allegro) asked for access to all Allegro scopes listed in the table. Now you can only apply for scopes that are actually necessary for the proper functioning of the application. If you do not take any steps, your application will authorize itself with the full scope list every time. We will display them to the user on the consent screen when confirming the connection of the application with the user’s account.

consent_scope_main


To limit the application’s access to only selected resources, you must provide the appropriate scopes when obtaining authorization - separate each subsequent scope with space (“%20”).

Sample request that allows the application to access only resources for managing offers and reading orders (for Authorization Code flow):

https://allegro.pl/auth/oauth/authorize?response_type=code&redirect_uri=http://www.example.com&client_id=438f71d3a26e4d829783a0a621873465&scope=allegro:api:sale:offers:write%20allegro:api:orders:read


Consent screen if the application is limited to use only resources for managing offers and reading orders:

consent_scope_short

Calling REST API resource

To perform a request to a selected REST API resource on behalf of a user, you should remember to pass an authorization token in the HTTP header. In addition to the token, you need to pass information on the resource version you are interested in:

curl -X GET \
  'https://api.allegro.pl/order/events' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'
value description
GET HTTP method used to call a resource (you can find information about it in the resource documentation)
Authorization HTTP header: Authorization. Bearer authorization (compliant with token_type returned upon token generation) together with access token received from OAuth
Accept The Accept header with a relevant value (resource version), required for GET queries to API (you can find information about it in the resource documentation)
https://api.allegro.pl/order/events Reference to a certain resource to be called

Extending token validity

The basic access token (access_token) is valid for 12 hours. In order to ensure that a user is not obliged to perform application authorization twice a day, we also make it possible to refresh tokens by refresh_token which is used to obtain a new access token for the user in a transparent way (without the need for the user to perform any actions). Such a token is valid for 3 months and after first refresh, you can use it for another 60 seconds.

information Thanks to so-called renewable token lifetime, each time you use the refresh token, you will receive a new pair - access token (valid for another 12 h) and refresh token (valid for another 3 months).

Sample request:

curl -X POST \
  'https://allegro.pl/auth/oauth/token?grant_type=refresh_token&refresh_token=eyJ...SDA&redirect_uri=http://exemplary.redirect.uri' \
  -H 'Authorization: Basic YTI...Hg=' \

Sample response:

{
  "access_token":"eyJ...dUA",                  -- access token which enables to perform 
                                               operations on API resources on behalf of 
                                               a user that is logged in
  "token_type":"bearer",                       -- token type (in our case: bearer)
  "refresh_token":"eyJ...QEQ",                 -- new single-use refresh token, that allows to
                                               extend the validity of user authorization 
                                               up to 3 months
  "expires_in":43199,                          -- validity time of access token 
                                               (in seconds; a token is valid for 12 hours)
  "scope":"allegro_api",                       -- scope of data/functionalities for which 
                                               the user authorised the application
  "allegro_api": true,                         -- flag which shows, that token was 
                                               generated for API purposes (no direct use)
  "jti":"2184f3be-f6de-4a66-bd8f-b11347d7ba80" -- JWT token identifier 
                                               (no direct application)
}

Check what apps are linked to your Allegro account

To check what apps are linked to your account go to the “Linked apps” (“Powiązane aplikacje”) tab in “My Allegro” (“Moje Allegro”).

Unlinking apps assigned to your Allegro accont

You can unlink the app in the “Linked apps” (“Powiązane aplikacje”) tab in “My Allegro” (“Moje Allegro”).