Clés API et authentification

Envoyez la clé comme jeton Bearer dans l’en-tête Authorization de chaque requête. La clé appartient à une organisation ; l’API détermine celle-ci à partir de la clé, sans autre en-tête pour l’indiquer. Un en-tête X-ORGANIZATION-ID envoyé avec elle est ignoré.

curl --request GET \
  --url https://api.serverside.com/v1/baremetal \
  --header 'Authorization: Bearer <api-key>'

L’API lit aussi la clé dans un en-tête X-API-KEY, alias du même identifiant. Une requête ne transmet qu’un identifiant : X-API-KEY avec Authorization, ou l’un de ces en-têtes envoyé deux fois, est refusé avec 400 (Erreurs d’authentification).

Créer une clé

La première clé se crée dans la console cloud : dans les paramètres de votre organisation, Manage API Keys propose le bouton Create an API Key. Il demande un nom et, éventuellement, les réseaux depuis lesquels la clé fonctionnera. La clé créée est affichée une seule fois et ne peut plus être consultée ; enregistrez-la immédiatement dans un gestionnaire de secrets ou une variable d’environnement.

Une clé comporte 63 caractères : org_, puis 59 caractères base64 compatibles avec les URL, pouvant inclure - et _. Seule une valeur Bearer commençant par org_ est interprétée comme clé API. Toute autre valeur est traitée comme un jeton de session console ; une clé collée sans son préfixe échoue donc avec 401.

Les clés se gèrent uniquement dans la console. Les points de terminaison qui créent, listent et modifient les clés nécessitent une session console connectée ; une clé ne peut donc pas en créer, lister ou modifier une autre.

Opérations inaccessibles à une clé

La référence API répertorie toutes les opérations accessibles à une clé. Le reste de l’API sert à la console cloud : paramètres de l’organisation, membres, invitations, rôles, clés API, notifications, profil utilisateur, tickets de support et listes des pays et devises. Chacune renvoie 401 à une clé avec ce corps :

{
  "success": false,
  "data": null,
  "code": "UNAUTHENTICATED",
  "message": "This endpoint requires a signed-in user session. Organization API keys are not accepted here.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B"
}

Permissions des clés

Une nouvelle clé reçoit toutes les permissions du rôle Admin intégré au jour de sa création, d’où le libellé Full Permissions dans la console. Cet ensemble n’est jamais actualisé ensuite. Une permission ajoutée ultérieurement manque aux clés antérieures ; un point de terminaison qui la vérifie leur répond 403. Une clé créée après ce changement la possède.

Chaque page de point de terminaison indique la permission vérifiée, par exemple organization.baremetal.deploy pour Déployer un système d’exploitation. Sept opérations n’en vérifient aucune et sont accessibles à toute clé de l’organisation : les listes et consultations des offres bare metal et blocs d’IP, Lister les régions, Obtenir les droits et Lister les clés SSH. Toutes les autres vérifient l’une des permissions suivantes :

Il n’est pas possible de créer des clés ayant moins de permissions que le rôle Admin ; une nouvelle clé les possède donc toutes.

Limiter une clé à vos réseaux

Une clé sans réseaux autorisés fonctionne depuis toute adresse. Dès qu’elle en possède au moins un, une requête provenant d’une adresse extérieure à tous ces réseaux est refusée comme si la clé était incorrecte. Une entrée est une adresse seule (198.51.100.7) ou un réseau CIDR (198.51.100.0/24), IPv4 ou IPv6, défini dans la console ; une nouvelle clé accepte jusqu’à 100 entrées.

L’API compare ces réseaux à l’adresse signalée par Cloudflare pour la connexion. Si une clé restreinte reçoit 401 dans l’outil d’essai des requêtes, exécutez la même requête avec cURL depuis une machine autorisée.

Désactiver une clé

Désactiver une clé dans la console l’arrête sans perdre ses paramètres ; la supprimer la retire définitivement. Une clé désactivée, supprimée ou expirée fait échouer toutes les requêtes comme une clé incorrecte. L’expiration est indépendante de l’interrupteur d’activation ; réactiver une clé expirée ne la rend donc pas utilisable.

Erreurs d’authentification

Une clé envoyée par les deux méthodes reçoit :

{
  "success": false,
  "data": null,
  "code": "VALIDATION_ERROR",
  "message": "X-API-KEY: Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
      "field": "X-API-KEY",
      "location": "header"
    }
  ]
}

Les deux réponses 401 incluent des en-têtes WWW-Authenticate nommant les identifiants acceptés : Bearer et ApiKey header="X-API-KEY" lorsqu’une clé fonctionne ; Bearer seul pour une opération réservée à la console, où il désigne le jeton de session console.

Le premier 401 ne précise pas quelle cause s’applique. Vérifiez dans cet ordre la clé et sa présence après Bearer , son état sous Manage API Keys dans la console, puis ses réseaux autorisés.