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

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 :
| Sujet | Gestion | Portée |
|---|---|---|
| Projet | Projet Settings > API Keys | Uniquement le projet dans lequel elle a été créée. Jamais la facturation, les membres, les invitations ni les clés elles-mêmes. |
| Organisation | Organisation Settings > API keys | Tous 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. |
| Personnelle | Compte Settings > API keys | Ce 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.
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
- Accédez à la page de gestion des clés pour le sujet souhaité (paramètres du projet, de l'organisation ou du compte)
- Cliquez sur Add API Key
- 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)
- Cliquez sur Create
- Copiez la clé immédiatement — elle ne sera plus affichée
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 :
| Preset | Description |
|---|---|
| Developer | Déployer et exécuter tout dans un projet, sans toucher aux membres ni à la facturation. |
| Maintainer | Tout ce qu'un developer peut faire, plus les personnes, les clés et les projets eux-mêmes. |
| Owner | Tout ce qui existe, y compris la vie de l'organisation elle-même. |
| Accountant | L'argent et rien d'autre : factures, moyens de paiement, coûts et consommation. |
| Read-only | Tout 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.
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.
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
| API | URL de base | Clés acceptées |
|---|---|---|
| API publique | https://app.sailops.io/api/public/api/v1 | Clés de projet uniquement |
| API (new) | https://app.sailops.io/api/v3 | Clé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
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
- Accédez à la page de gestion des clés pour le sujet (paramètres du projet, de l'organisation ou du compte)
- Sélectionnez l'onglet API Keys
- Consultez toutes les clés actives avec leur label, description, scopes, date de création et expiration
Informations affichées sur les clés
| Champ | Description |
|---|---|
| Label | Identifiant de la clé |
| Description | Description optionnelle de la clé |
| Scopes | Ce à quoi la clé est restreinte, ou « Everything its subject allows » si non restreinte |
| Expires At | Date d'expiration (si définie) |
| Created At | Horodatage de création |
Supprimer une clé
- Trouvez la clé dans la liste
- Cliquez sur Delete
- Confirmez la suppression
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 :
- Créez une nouvelle clé
- Mettez à jour tous les systèmes avec la nouvelle clé
- Vérifiez que la nouvelle clé fonctionne
- 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
| Code | Statut HTTP | Description |
|---|---|---|
UNAUTHORIZED | 401 | Clé API invalide ou manquante |
EXPIRED_AUTHENTICATION | 401 | La clé API a expiré |
FORBIDDEN | 403 | Permissions insuffisantes, ou une clé non-projet utilisée sur l'API publique |
NOT_FOUND | 404 | Ressource non trouvée |
CONFLICT | 409 | Une clé API avec ce label existe déjà dans le sujet |
REQUEST_VALIDATION | 400 | Corps de requête invalide |
INTERNAL | 500 | Erreur interne du serveur |
Débogage
- Vérifiez que la clé n'a pas expiré
- Vérifiez que le sujet de la clé correspond à l'API appelée (l'API publique exige une clé de projet)
- Vérifiez que le nom de la ressource est correct
- Assurez-vous que le corps de la requête est du JSON valide
- Notez le
traceIddans 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
- API (new) — Clés d'API — Créer et gérer les clés des trois sujets
- Intégration CI/CD — Guides de déploiement GitHub Actions et GitLab CI
- Vue d'ensemble de l'API publique — URL de base, authentification et format d'erreur
- Référence des endpoints — Tous les endpoints de l'API publique par catégorie
- Stack Engine — Infrastructure-as-code déclarative avec des stacks YAML
- Serveur MCP — Connecter des assistants IA pour gérer votre projet
- Configuration des conteneurs
- Obtenir de l'aide