Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 30 ยท APIs and Integrations

The Admin API in PrestaShop 9

Understand the PrestaShop 9 Admin API: OAuth2 client credentials, scopes, API Platform resources and custom endpoints, with a runnable token and scope stand-in.

The classic Webservice authenticates with a long-lived key and exposes data close to the database tables. PrestaShop 9 adds a second, newer interface: the Admin API. It is built on the API Platform framework, it speaks JSON, it is protected with OAuth2, and its resources are modeled on the same commands and queries the modern back office uses. For an integration, that means short-lived tokens, permissions called scopes, generated documentation and operations that mean something to the business ("create a product"), rather than "insert a row".

This lesson explains the client credentials flow, scopes, how resources and custom endpoints are described, and what a safe integration looks like. The Admin API is young and its details move between releases, so every PrestaShop-specific snippet below is read-only and conservative: treat addresses, scope names and file locations as a pattern and confirm them on the Admin API page of your shop and in the developer documentation for your version. The stand-ins implement the mechanics that never change (signed tokens, expiry, scope checks, 401 versus 403) so you can run and break them.

What changed compared with the Webservice

Webservice Admin API (PrestaShop 9)
Credential Static key, Basic auth OAuth2 client id and secret, exchanged for a token
Lifetime Until you delete the key Token expires, secret can be rotated
Permission model Verb per resource Scopes (read and write per resource)
Formats XML or JSON JSON
Data model Close to ObjectModel and tables Resources built on back office commands and queries
Documentation Hand-written Generated from the resource definitions

The Webservice continues to exist, and many shops will use both for years. Choose the Admin API for new integrations on PrestaShop 9 when the resource you need exists there, and the Webservice where it does not.

OAuth2 client credentials

OAuth2 has several "grant types". Server-to-server integrations (a nightly sync, an ERP connector) use client credentials: there is no human logging in, only a program that proves who it is.

sequenceDiagram
    participant App as "Your integration"
    participant Shop as "PrestaShop Admin API"
    App->>Shop: "POST /token<br/>client_id, client_secret, scope"
    Shop-->>App: "access_token, expires_in"
    App->>Shop: "GET /products<br/>Authorization: Bearer access_token"
    Shop-->>App: "200 JSON"
    Note over App,Shop: "When expires_in has passed, ask for a new token"

The secret is sent only to the token endpoint. Every other request carries the short-lived bearer token.

You prepare this in the back office. On the Admin API page you create an API client: a name, a client id, a secret (shown once, so store it at once in a password manager or your server's environment), a token lifetime, and the scopes it may request. Then the integration asks for a token:

Terminal
# read-only: cannot run on this site. The path contains your admin folder name.
curl -X POST 'https://your-shop.example/admin-dev/api/oauth2/token' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=my-erp-sync' \
  -d 'client_secret=THE_SECRET_SHOWN_ONCE' \
  -d 'scope=product_read product_write'

The answer is a small JSON document with the token and how long it lives:

JSON
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi..."
}

Then each call carries the token in a header:

Terminal
curl -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...' \
  'https://your-shop.example/admin-dev/api/products'

Treat the exact paths above as an example. The admin folder name is part of the URL, and the Admin API page and the generated API documentation of your shop show the real addresses.

Scopes

A scope is a named permission. Scope names follow a read/write pattern per resource, for example one scope to read products and another to change them. The client page lists the scopes your PrestaShop version offers. The rules are the usual OAuth2 ones:

  • A client is configured with a set of scopes it may have.
  • A token request asks for the scopes it wants now, and gets at most the allowed ones.
  • Each endpoint requires a scope. A valid token without it is refused.

Ask for the narrowest set that does the job. A report generator needs only read scopes; if it leaks, nobody can change your catalog with it.

Resources and operations

Resources in the Admin API are described with API Platform. A resource is a PHP class with attributes that name its operations, the scopes they need and how requests map to the back office's own application layer. The core resources map operations to CQRS commands and queries: a read operation runs a query, a create operation runs a command, and the same command is what the back office calls when an employee clicks Save. That is why rules such as validation and events behave the same through the API and through the screen.

A sketch of what a resource looks like, to show the idea (this is simplified; the real attribute classes and their arguments depend on the version):

PHP
<?php
// read-only sketch, not copy-paste code
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(
    operations: [
        // GET /notes/{noteId}       -> runs a query, needs the read scope
        // POST /notes               -> runs a command, needs the write scope
        // GET /notes                -> paginated list, needs the read scope
    ],
    scopes: ['acme_note_read', 'acme_note_write'],
)]
class Note
{
    public int $noteId;
    public int $customerId;
    public string $content;
}

The important design points, which hold whatever the exact syntax:

  1. The resource is a data transfer object, not a database row. Its shape is part of your public contract.
  2. Reads and writes are separate operations with separate scopes.
  3. Writes go through a command, so validation and domain events run in one place.
  4. The documentation is generated from these definitions, so keeping them accurate keeps the docs accurate.

Custom endpoints from a module

A module can add its own resources so that its data or actions appear in the same API, with the same authentication and documentation. In outline:

  1. Write the resource class with its operations and scopes.
  2. Provide a query or command (and handler) behind each operation, registered as services, as in The Symfony Back Office.
  3. Put the resource class where the core looks for module API resources, and clear the cache. The documentation of your version names the folder and the registration rules; because the feature is recent, confirm them there.
  4. Define the scopes your endpoints need so that API clients can be granted them.

For simple data exposure on older versions, the Webservice resource hook remains the established route.

A token flow you can run

The stand-in below implements the three checks every OAuth2 resource server performs: is the signature genuine, is the token still valid, does it carry the right scope. Real tokens are JWTs signed by the shop with its own keys; here the token is a base64url-encoded JSON payload plus an HMAC, which has the same shape and checks without a library. The clock is passed in so the output is always the same.

PHP Stand-in: issue a token, verify it, let it expire

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The two failure codes are worth remembering: 401 means "I do not accept who you say you are" (no token, bad signature, expired), and 403 means "I know who you are, and you may not do this" (valid token, missing scope). Clients react differently: on a 401 they fetch a new token; on a 403 asking again will never help.

A small resource server you can run

The second stand-in puts the token behind a router. It maps operations to queries and commands, requires a scope for each, validates the body of a write (returning 422 with field errors) and uses a tiny token store so the example stays short. The shape of the answers follows common API conventions; it is not the exact PrestaShop output.

PHP Stand-in: scoped endpoints that run queries and commands

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The report bot can read but its attempted write is refused with 403 before any command runs. The ERP's invalid write returns 422 with a reason per field and changes nothing. Money travels as integer cents, as discussed in money as integers.

Building a safe integration

  • Keep secrets out of code. Read the client secret from the environment or a secrets manager; never commit it. Rotate it if someone who knew it leaves.
  • Cache the token until shortly before it expires, then ask for a new one. Requesting a token for every call wastes time and hits the token endpoint hard.
  • Handle 401 and 403 differently: refresh on 401 (once), report configuration on 403.
  • Use the narrowest scopes and one API client per integration, so you can revoke one.
  • Make writes safe to retry. Networks fail; use an idempotency key or natural keys so a retried "create" does not create two. See idempotency.
  • For events going the other way, from the shop to your system, use signed webhooks and verify the signature, as in webhooks and signatures.
  • Always HTTPS. Bearer tokens are as good as passwords until they expire.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which OAuth2 grant type fits a nightly server-to-server sync with no human logging in?

    Client credentials let a program prove its identity with a client id and secret and get a token, with no user involved.
  2. 2. A request has a valid token that lacks the scope the endpoint needs. Which status is correct?

    401 means the identity is not accepted (missing, expired or forged token). 403 means the identity is known but not allowed, which is the missing-scope case.
  3. 3. Why is the client secret shown only once and sent only to the token endpoint?

    The secret is the long-lived credential. Limiting where it travels, and using expiring tokens everywhere else, limits what a leak can do.
  4. 4. How do Admin API write operations relate to the back office?

    Mapping operations to commands and queries keeps rules, validation and events in one place for the screen and for the API.
  5. 5. What should an integration do when the token's expires_in time has passed?

    Tokens are short-lived by design. Cache one until shortly before it expires, then fetch a new one.

Summary

  • The PrestaShop 9 Admin API is JSON over OAuth2: exchange a client id and secret for a short-lived bearer token, then call resources with it.
  • Scopes are read and write permissions per resource; request the narrowest set and use one API client per integration.
  • Resources are API Platform definitions whose operations map to back office commands and queries, and modules can add their own.
  • Resource servers check signature, expiry and scope: 401 for identity problems, 403 for missing permission, 422 for invalid input.
  • Keep secrets out of code, cache tokens, retry safely and verify webhook signatures; confirm exact paths and scope names on your shop's Admin API page.

Next: Payment Modules