6

Piwigo Web API

Linty edited this page 2025-12-02 12:06:33 +01:00

Table of Contents

• API Key authentication
• Generate an API key
• Use an API key
• Restrictions and security

API = Application Programming Interface. This is the way other applications can communicate with Piwigo. This feature is also know as Web Services.

Examples:

• Wordpress (web blog software) can display random photos from a Piwigo gallery in its sidebar
• Lightroom (photo management software for desktop) can create albums and upload photos to Piwigo

This documentation is under construction: not all methods are described here. You won't have to find methods by yourself in Piwigo source code, we have a web API browser, distributed in Piwigo itself. On any Piwigo installation, go to http://yourdomain/yourpiwigo/tools/ws.htm from your web browser and discover all methods. For example web API browser on Piwigo demo.

---

API Key authentication

Since Piwigo 16, each user can generate one or more personal API keys from their profile. These keys allow secure, stateless access to the Piwigo web API without requiring a user session.

🚨 Important change between Piwigo 16.0.0 and 16.1.0:

• Use the X-PIWIGO-API header instead of Authorization when sending API keys.#2460

Generate an API key

1. Log in to your Piwigo account.
2. Go to your user profile and open the API Keys section.
3. Click on New API Key.
4. Choose a name and a validity duration (in days or a custom expiration date).
5. Copy and save the secret key: it will never be displayed again.

Use an API key

• To authenticate your API requests, use the X-PIWIGO-API HTTP header:
  X-PIWIGO-API: pkid-XXXXXXXX-XXXXXXXXXXXX:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

  • pkid-XXX... = public identifier of the key
  • YYYYY... = secret key
    Don't forget : between them

• Example with curl:

curl -H "X-PIWIGO-API: pkid-20250609-abcdef1234567890:0123456789abcdef0123456789abcdef01234567" \
  -d "method=pwg.categories.getList" \
  -d "format=json" \
  https://your-piwigo/ws.php

Restrictions and security

• Some sensitive methods are explicitly blocked for API key usage (see the prohibited methods by default, you can also add or remove methods in $conf['api_key_forbidden_methods']).
• A key can be revoked or renamed at any time from the profile.
• An expired or revoked key can no longer be used to access the API.
• Access is tracked (date last used).
• The secret key is displayed only once on creation.
• Providing pwg_token becomes useless

Test your keys:

Use the built-in tool https://your-piwigo/tools/ws.htm
An X-PIWIGO-API field lets you test your requests with an API key.

Best practices:

• Use a different key for each application or script.
• Revoke unused keys.
• Never share the secret key.