adam/Piwigo
1
0
Fork 0
mirror of https://github.com/Piwigo/Piwigo.git synced 2026-08-12 03:33:01 +02:00
Code Issues Packages Projects Releases Wiki Activity

add API Key authentication doc

Linty
2025-06-09 20:26:49 +02:00
parent 34716babc0
commit b3f32f23eb
1 changed files with 51 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Piwigo-Web-API.md
+51 -1
@@ -14,4 +14,54 @@ 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](https://demo1.piwigo.com/tools/ws.htm).
on Piwigo demo](https://demo1.piwigo.com/tools/ws.htm).
***
## 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.
### 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 `Authorization` HTTP header:\
`Authorization: pkid-XXXXXXXX-XXXXXXXXXXXX:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY`
* `pkid-XXX...` = public identifier of the key
* `YYYYY...` = secret key\
_Don't forget `:` between them_
* Example with curl:
```
curl -H "Authorization: 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](https://github.com/Piwigo/Piwigo/tree/master), 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.
Test your keys:
Use the built-in tool `https://your-piwigo/tools/ws.htm`\
An `Authorization` 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.