Permissions (scopes)
Une clé ne fait que ce que vous avez coché. Les permissions se nomment ressource:accès. Un appel hors permission répond 403 API_SCOPE_MISSING:<scope>, et le suffixe nomme la permission à ajouter.
Le catalogue
| Permission | Routes ouvertes |
|---|---|
account:read | GET /me |
account.notifications:read | GET /account/notifications |
account.access:read | GET /account/access |
account.ssh_keys:read | GET /ssh-keys, GET /ssh-keys/{id} |
account.ssh_keys:write | POST /ssh-keys, DELETE /ssh-keys/{id} |
services:read | GET /services, GET /services/{code} |
services:write | PATCH /services/{code} ; POST /services/{code}/renew avec billing.invoices:pay |
services.metrics:read | GET /services/{code}/status, GET /services/{code}/metrics/history |
services.addons:read | GET /services/{code}/addons |
services.power:write | POST /services/{code}/power ; actions power, start_vps, stop_vps, reboot_vps |
services.console:write | POST /services/{code}/console/command ; action send_console_command |
services.backups:read | GET /services/{code}/backups ; action backup_list |
services.backups:write | POST /services/{code}/backups, DELETE /services/{code}/backups/{backupId}, POST /services/{code}/backups/restore ; actions backup_create, backup_delete, backup_restore |
services.firewall:read | action firewall_list |
services.firewall:write | actions firewall_create, firewall_update, firewall_move, firewall_delete |
services.rdns:write | action rdns, y compris op: "get" |
services.reinstall:write | POST /services/{code}/reinstall |
billing.invoices:read | GET /invoices, GET /invoices/{code}, GET /invoices/{code}/pdf |
billing.credit_notes:read | GET /credit-notes, GET /credit-notes/{code}/pdf |
billing.balance:read | GET /balance, GET /balance/transactions |
billing.payment_methods:read | GET /payment-methods |
billing.invoices:pay | POST /invoices/{code}/pay, POST /orders/{orderNumber}/pay, POST /services/{code}/renew ; POST /orders quand il paie |
billing.saved_methods:charge | les quatre routes ci-dessus quand le financement est saved_method ou account_default. Ne s'utilise jamais seul |
catalog:read | GET /catalog/products, GET /catalog/products/{shortname} |
orders:read | GET /orders, GET /orders/{orderNumber} |
orders:write | POST /orders |
tickets:read | GET /tickets, GET /tickets/{ticketNumber} |
tickets:write | POST /tickets, POST /tickets/{ticketNumber}/messages, POST /tickets/{ticketNumber}/close |
Deux routes échappent au tableau : GET /me/key ne demande aucune permission, et GET /v1/openapi.json ne demande aucune clé.
POST /services/{code}/actions/{action} n'a pas de permission fixe. Elle dépend de l'action envoyée : voir la colonne « actions » ci-dessus et le tableau complet dans Gérer vos services.
Comment un :write implique un :read
Un :write implique le :read du même nom exact, rien de plus.
| Vous avez | Vous obtenez aussi |
|---|---|
services:write | services:read |
services.backups:write | services.backups:read |
services.firewall:write | services.firewall:read |
account.ssh_keys:write | account.ssh_keys:read |
orders:write | orders:read |
tickets:write | tickets:read |
Ce qui ne s'implique pas, malgré le préfixe commun :
services:writene donne niservices.metrics:read, niservices.backups:read, niservices.addons:read, niservices.firewall:read.billing.invoices:payne donne pasbilling.invoices:read: payer une facture et la lire sont deux permissions.services.rdns:writeetservices.reinstall:writen'ont pas de:readcorrespondant.
Ce que la permission ne suffit pas à obtenir
Les droits effectifs sont l'intersection de la permission, de la restriction de services de la clé, et de l'état du service.
| Cas | Réponse |
|---|---|
| Service hors de la restriction de la clé | 404 SERVICE_NOT_FOUND |
Service suspendu ou résilié, routes relayées (/power, /console/command, /actions/{action}) | 409 SERVICE_NOT_ACTIVE |
| Service suspendu ou résilié, routes déléguées (sauvegardes, restauration, réinstallation) | 400 SERVICE_NOT_ACTIVE |
| Service en recouvrement, mêmes routes déléguées | 400 SERVICE_IN_DUNNING |
| Service sans instance provisionnée | 409 sur les routes relayées, 400 INSTANCE_NOT_PROVISIONED sur les déléguées |
| Action inconnue de la plateforme | 403 API_ACTION_NOT_ALLOWED:<action> |
Choisir les permissions
- Partez de ce que l'intégration fait aujourd'hui. Élargir une clé demande une confirmation d'identité, pas une nouvelle clé.
- Une supervision ou un export comptable n'a besoin que de permissions
:read. billing.saved_methods:chargene va que sur la clé qui doit débiter, avec un plafond à la mesure de la tâche. C'est la seule permission qui impose un plafond.services.reinstall:writedétruit le disque. Réservez-la à la clé qui réinstalle.