Aller au contenu principal

API Keys

Créez et gérez des clés API pour l'accès programmatique à SailOps.

Clés API du Projet

Vue d'Ensemble​

Les clés API fournissent un accès authentifié à SailOps. Utilisations courantes :

  • Automatiser les déploiements via des pipelines CI/CD
  • Mettre à jour les images de conteneurs de manière programmatique
  • Configurer les variables d'environnement et les fichiers
  • Gérer l'infrastructure de manière déclarative avec le Stack Engine
  • Connecter des assistants IA via le serveur MCP

Sujets des clés​

Chaque clé API appartient à l'un de trois sujets, qui détermine ce qu'elle peut atteindre :

SujetGestionPortée
ProjetProjet Settings > API KeysUniquement le projet dans lequel elle a été créée. Jamais la facturation, les membres, les invitations ni les clés elles-mêmes.
OrganisationOrganisation Settings > API keysTous les projets de l'organisation, avec ce que détient un DEVELOPER. Les membres, les invitations et l'organisation elle-même restent hors de portée.
PersonnelleCompte Settings > API keysCe que vous atteignez au moment de chaque requête. Si vous perdez un rôle, la clé le perd avec vous. Jamais l'administration de la plateforme, les clés, les modifications de facturation ni les paiements.

L'API (new) accepte les trois. L'API publique et le serveur MCP n'acceptent que les clés de projet — une clé d'organisation ou personnelle reçoit une erreur FORBIDDEN.

Rôle requis

La gestion des clés de projet nécessite au minimum le rôle Maintainer sur le projet. La gestion des clés d'organisation nécessite le rôle Owner sur l'organisation.

Créer une clé API​

  1. Accédez à la page de gestion des clés pour le sujet souhaité (paramètres du projet, de l'organisation ou du compte)
  2. Cliquez sur Add API Key
  3. Configurez la clé :
    • Label : Identifiant descriptif (ex : "my-api-key") — doit être unique au sein du sujet
    • Description : Description optionnelle (ex : "Key for CI/CD pipeline")
    • Expiration Date : Date d'expiration optionnelle
    • Permissions : Choisissez ce que la clé peut faire (voir Choisir les permissions ci-dessous)
  4. Cliquez sur Create
  5. Copiez la clé immédiatement — elle ne sera plus affichée
Important

La clé API n'est affichée qu'une seule fois. Stockez-la de manière sécurisée immédiatement après sa création.

Choisir les permissions​

Le sélecteur de permissions affiche deux panneaux côte à côte : Available à gauche et Selected à droite. Cliquez sur une permission pour la déplacer ; utilisez Add everything shown ou Remove everything shown pour déplacer en masse.

Les presets permettent de démarrer depuis un ensemble prêt à l'emploi au lieu de choisir un par un. Les presets disponibles sont :

PresetDescription
DeveloperDéployer et exécuter tout dans un projet, sans toucher aux membres ni à la facturation.
MaintainerTout ce qu'un developer peut faire, plus les personnes, les clés et les projets eux-mêmes.
OwnerTout ce qui existe, y compris la vie de l'organisation elle-même.
AccountantL'argent et rien d'autre : factures, moyens de paiement, coûts et consommation.
Read-onlyTout voir, ne rien modifier.

Un preset est borné par ce que vous détenez vous-même — les permissions que vous ne pouvez pas donner sont comptées et signalées, pas ignorées en silence. Après avoir appliqué un preset, vous pouvez toujours ajouter ou retirer des permissions individuellement.

Recherche

Le champ de recherche correspond aux noms de permissions, aux descriptions et aux chemins d'API. Tapez /billing pour trouver toutes les permissions qui touchent un endpoint de facturation — utile quand vous savez quel appel API vous devez atteindre.

Ensemble par défaut

Laissez les permissions vides pour l'ensemble par défaut : l'expansion DEVELOPER pour les clés d'organisation et de projet, ou votre propre accès pour une clé personnelle.

Utiliser les clés API​

Authentification​

Incluez la clé API dans l'en-tête X-Api-Key :

curl -H "X-Api-Key: $SAILOPS_API_KEY" \
https://app.sailops.io/api/public/api/v1/containers/mon-conteneur

Quelle API utiliser​

APIURL de baseClés acceptées
API publiquehttps://app.sailops.io/api/public/api/v1Clés de projet uniquement
API (new)https://app.sailops.io/api/v3Clés de projet, d'organisation et personnelles

Consultez la référence des endpoints de l'API publique et la référence des endpoints de l'API (new) pour les listes complètes.

Les clés SailOps n'authentifient pas les appels à Grafana. Utilisez un token de Service Account Grafana pour son API.

Exemples courants​

Mettre à jour l'image d'un conteneur (cas CI/CD typique) :

curl -X PATCH \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "ghcr.io/myorg/api:v1.2.0"
}' \
https://app.sailops.io/api/public/api/v2/containers/my-container

Configurer les variables d'environnement d'un conteneur :

curl -X PATCH \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"config": {
"environment": [
{"key": "DATABASE_URL", "type": "secret", "value": "postgres://..."},
{"key": "LOG_LEVEL", "type": "config", "value": "info"}
],
"files": [
{"name": "config-yaml", "path": "/app/config.yaml", "type": "config", "content": "key: value"}
]
}
}' \
https://app.sailops.io/api/public/api/v2/containers/my-container

Obtenir les tarifs (aucune authentification requise) :

curl https://app.sailops.io/api/public/api/v1/pricing
Stack Engine pour les déploiements IaC

Pour les workflows CI/CD qui gèrent plusieurs ressources (conteneurs, bases de données, gateways), envisagez le Stack Engine. Il permet de définir toute votre infrastructure dans un seul fichier YAML et de l'appliquer en un seul appel API — avec une étape de plan dry-run avant d'appliquer les changements.

Intégration CI/CD​

GitHub Actions​

name: Déployer sur SailOps

on:
push:
branches: [main]

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Build et push de l'image
run: |
docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

- name: Déployer sur SailOps
run: |
curl -X PATCH \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d "{\"image\": \"ghcr.io/${{ github.repository }}:${{ github.sha }}\"}" \
https://app.sailops.io/api/public/api/v2/containers/${{ vars.CONTAINER_NAME }}

GitLab CI​

deploy:
stage: deploy
script:
- |
curl -X PATCH \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"image\": \"$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA\"}" \
https://app.sailops.io/api/public/api/v2/containers/$CONTAINER_NAME
only:
- main

Jenkins​

pipeline {
agent any
environment {
SAILOPS_API_KEY = credentials('sailops-api-key')
}
stages {
stage('Deploy') {
steps {
sh '''
curl -X PATCH \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\\"image\\": \\"monregistre/app:${BUILD_NUMBER}\\"}" \
https://app.sailops.io/api/public/api/v2/containers/${CONTAINER_NAME}
'''
}
}
}
}

Gérer les clés API​

Voir les clés​

  1. Accédez à la page de gestion des clés pour le sujet (paramètres du projet, de l'organisation ou du compte)
  2. Sélectionnez l'onglet API Keys
  3. Consultez toutes les clés actives avec leur label, description, scopes, date de création et expiration

Informations affichées sur les clés​

ChampDescription
LabelIdentifiant de la clé
DescriptionDescription optionnelle de la clé
ScopesCe à quoi la clé est restreinte, ou « Everything its subject allows » si non restreinte
Expires AtDate d'expiration (si définie)
Created AtHorodatage de création

Supprimer une clé​

  1. Trouvez la clé dans la liste
  2. Cliquez sur Delete
  3. Confirmez la suppression
Effet Immédiat

Les clés supprimées sont immédiatement invalides. Mettez à jour tous les systèmes utilisant la clé avant de la supprimer.

Rotation des clés​

Bonne pratique pour la rotation des clés :

  1. Créez une nouvelle clé
  2. Mettez à jour tous les systèmes avec la nouvelle clé
  3. Vérifiez que la nouvelle clé fonctionne
  4. Supprimez l'ancienne clé

Erreurs API​

Format des réponses d'erreur​

{
"code": "ERROR_CODE",
"traceId": "abc123",
"message": "Message lisible par l'utilisateur"
}

Codes d'erreur courants​

CodeStatut HTTPDescription
UNAUTHORIZED401Clé API invalide ou manquante
EXPIRED_AUTHENTICATION401La clé API a expiré
FORBIDDEN403Permissions insuffisantes, ou une clé non-projet utilisée sur l'API publique
NOT_FOUND404Ressource non trouvée
CONFLICT409Une clé API avec ce label existe déjà dans le sujet
REQUEST_VALIDATION400Corps de requête invalide
INTERNAL500Erreur interne du serveur

Débogage​

  1. Vérifiez que la clé n'a pas expiré
  2. Vérifiez que le sujet de la clé correspond à l'API appelée (l'API publique exige une clé de projet)
  3. Vérifiez que le nom de la ressource est correct
  4. Assurez-vous que le corps de la requête est du JSON valide
  5. Notez le traceId dans la réponse d'erreur pour le support

Bonnes pratiques de sécurité​

1. Utiliser des dates d'expiration​

Définissez une expiration pour les accès temporaires :

Prestataire court terme : 30 jours
Pipeline CI/CD : 1 an
Intégration : Pas d'expiration (rotation manuelle)

2. Stockage sécurisé​

Ne commitez jamais les clés API dans le code :

✓ Variables d'environnement
✓ Gestionnaires de secrets (Vault, AWS Secrets Manager)
✓ Secrets CI/CD

✗ Dépôts de code
✗ Fichiers de configuration
✗ Messages de chat

3. Rotation régulière​

Faites tourner les clés périodiquement :

  • Tous les 90 jours pour la production
  • Immédiatement après le départ d'un membre de l'équipe
  • Après tout incident de sécurité

4. Auditer l'utilisation​

Surveillez l'utilisation des clés API via le journal d'audit. Les actions d'une clé personnelle apparaissent dans votre propre journal ; celles d'une clé d'organisation ou de projet apparaissent dans le journal de l'entité à laquelle elle appartient.

Sujets connexes​