Clés API

Apprenez à gérer l'authentification pour CLI et accès API dans TeamDay.

Table des matières

Méthodes d'authentification
Jetons d'accès personnel
OAuth pour CLI
Meilleures pratiques de sécurité
Dépannage

Méthodes d'authentification

TeamDay prend en charge deux méthodes d'authentification :

Méthode	Cas d'usage	Expiration	Meilleur pour
OAuth 2.1	Utilisation interactive CLI	15 min (jeton d'accès) 90 jours (jeton de rafraîchissement)	Utilisateurs humains, développement
Jeton d'accès personnel (PAT)	Automation API	Révocation manuelle uniquement	CI/CD, scripts, automation

OAuth vs PAT

Utilisez OAuth quand :

Travailler interactivement avec CLI
Vous êtes un utilisateur humain
Vous voulez un rafraîchissement de token automatique
L'accès à court terme est préféré

Utilisez PAT quand :

Automatiser avec des scripts ou CI/CD
Exécuter des jobs en arrière-plan
Besoin d'accès long terme
Voulez une authentification simple bearer token

Jetons d'accès personnel

Les jetons d'accès personnels (PATs) sont des identifiants à longue durée de vie pour l'accès programmatique.

Créer un PAT

Via l'interface :

Étape 1 : Naviguer vers les paramètres

Cliquez sur votre icône de profil → Paramètres

Étape 2 : Aller aux clés API

Cliquez sur "Clés API" dans la barre latérale gauche

Étape 3 : Cliquez sur "Créer le token"

Cliquez sur le bouton "+ Nouveau token d'accès personnel"

Étape 4 : Configurer le token

Nom (Obligatoire)
- Nom descriptif pour ce token
- Exemples : "Pipeline CI/CD", "Scripts d'automation", "Production Bot"
Expiration (Optionnel)
- Par défaut : Pas d'expiration
- Options : 30 jours, 90 jours, 1 an, personnalisé, jamais
- Recommandation : Définir une expiration pour la sécurité
Scopes (À venir)
- Actuellement : Accès complet
- Futur : Permissions fine-grained (agents:read, tasks:write, etc.)

Étape 5 : Copier le token

⚠️ IMPORTANT : Token affiché une seule fois !

td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Copier immédiatement et stocker de manière sécurisée
Si perdu, vous devez révoquer et créer un nouveau token
Ne jamais commit sur git ou partager publiquement

Étape 6 : Enregistrer le token de manière sécurisée

Stocker dans un gestionnaire de mots de passe ou une variable d'environnement sécurisée :

# .bashrc ou .zshrc
export TEAMDAY_API_TOKEN="td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Utiliser les PATs

Avec CLI :

# Méthode 1 : Définir via la commande
teamday auth set-key "td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Méthode 2 : Variable d'environnement
export TEAMDAY_API_TOKEN="td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
teamday agents list

# Méthode 3 : Inline
TEAMDAY_API_TOKEN="td_xxx" teamday agents list

Avec API :

curl -X GET https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Avec JavaScript :

const TEAMDAY_TOKEN = process.env.TEAMDAY_API_TOKEN;

const response = await fetch('https://cc.teamday.ai/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${TEAMDAY_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

const agents = await response.json();

Avec Python :

import os
import requests

TEAMDAY_TOKEN = os.environ['TEAMDAY_API_TOKEN']

response = requests.get(
    'https://cc.teamday.ai/api/v1/agents',
    headers={
        'Authorization': f'Bearer {TEAMDAY_TOKEN}',
        'Content-Type': 'application/json'
    }
)

agents = response.json()

Gérer les PATs

Afficher les tokens actifs :

Via l'interface :

Paramètres → Clés API
Voir la liste des tokens actifs avec :
- Nom
- Date de création
- Date de dernière utilisation
- Expiration (si définie)

Les tokens sont hashés - Vous ne pouvez pas afficher la valeur du token après la création.

Via CLI :

teamday auth tokens list

Sortie :

ID          Name                    Created      Last Used    Expires
---------------------------------------------------------------------------
token_123   CI/CD Pipeline          2024-12-01   2025-01-15   2025-06-01
token_456   Production Bot          2024-10-15   2025-01-14   Never
token_789   Local Development       2025-01-10   2025-01-15   2025-02-10

Révoquer les PATs

Via l'interface :

Paramètres → Clés API
Trouver le token dans la liste
Cliquez sur "⋯" → "Révoquer"
Confirmez

Via CLI :

teamday auth tokens revoke token_123

Effet :

Le token cesse immédiatement de fonctionner
Toutes les requêtes avec ce token renvoient 401 Unauthorized
Impossible à annuler - vous devez créer un nouveau token

Quand révoquer :

Token potentiellement compromis
Un employé quitte l'équipe
Basculer vers un nouveau token
Token n'est plus nécessaire

Rotation des tokens

Meilleure pratique : Rotation des tokens régulièrement

Stratégie :

Créer un nouveau token
Mettre à jour les systèmes pour utiliser le nouveau token
Vérifier que le nouveau token fonctionne
Révoquer l'ancien token

Script exemple :

#!/bin/bash
# rotate-token.sh

# Créer un nouveau token (via UI, copier la valeur)
NEW_TOKEN="td_new_token_here"

# Mettre à jour dans CI/CD (exemple : GitHub Actions)
gh secret set TEAMDAY_API_TOKEN --body "$NEW_TOKEN"

# Mettre à jour dans l'environnement de production
kubectl create secret generic teamday-token \
  --from-literal=token="$NEW_TOKEN" \
  --dry-run=client -o yaml | kubectl apply -f -

# Tester le nouveau token
TEAMDAY_API_TOKEN="$NEW_TOKEN" teamday agents list

# Si réussi, révoquer l'ancien token
teamday auth tokens revoke token_old_id

OAuth pour CLI

OAuth fournit un accès sécurisé et à courte durée de vie pour les utilisateurs CLI.

Comment fonctionne OAuth

sequenceDiagram
    participant CLI
    participant Browser
    participant TeamDay

    CLI->>TeamDay: 1. Initier l'auth
    TeamDay->>CLI: 2. Retourner le code auth + URL
    CLI->>Browser: 3. Ouvrir l'URL d'auth
    Browser->>TeamDay: 4. L'utilisateur se connecte
    TeamDay->>Browser: 5. Succès de l'autorisation
    CLI->>TeamDay: 6. Sonder les tokens
    TeamDay->>CLI: 7. Retourner les tokens d'accès + rafraîchissement
    CLI->>TeamDay: 8. Faire des requêtes API
    Note over CLI,TeamDay: Le token d'accès expire dans 15 min
    CLI->>TeamDay: 9. Rafraîchir le token
    TeamDay->>CLI: 10. Nouveau token d'accès

Se connecter avec OAuth

Étape 1 : Exécuter la commande de connexion

teamday auth login

Étape 2 : CLI initie l'auth

Initialiser l'authentification...

Veuillez ouvrir cette URL dans votre navigateur :
https://cc.teamday.ai/cli-auth?code=abc123xyz

En attente d'autorisation...

Étape 3 : Navigateur s'ouvre automatiquement

Si le navigateur ne s'ouvre pas, copier/coller l'URL manuellement
Vous verrez la page de connexion TeamDay

Étape 4 : Se connecter à TeamDay

Entrer l'email/mot de passe
Ou utiliser le fournisseur OAuth (Google, GitHub)

Étape 5 : Autoriser CLI

La page affiche :

Autoriser CLI TeamDay

TeamDay CLI demande l'accès à votre compte.

Cela permettra :
✓ Gérer les agents
✓ Exécuter les agents
✓ Accéder aux espaces
✓ Créer des tâches

[Autoriser] [Annuler]

Cliquez sur "Autoriser"

Étape 6 : Succès

Le navigateur affiche :

✓ Autorisation réussie !

Vous pouvez fermer cette fenêtre et revenir à votre terminal.

CLI affiche :

✓ Authentification réussie !

Vous êtes maintenant connecté en tant que : [email protected]
Organisation : Acme Corp

Stockage des tokens

Les tokens OAuth sont stockés localement :

Localisation :

macOS : ~/.teamday/config.json
Linux : ~/.teamday/config.json
Windows : %USERPROFILE%\.teamday\config.json

Contenu :

{
  "accessToken": "ey...",
  "refreshToken": "ey...",
  "expiresAt": "2025-01-15T11:00:00Z",
  "user": {
    "email": "[email protected]",
    "organizationId": "org_abc123"
  }
}

Sécurité :

Le fichier a des permissions strictes (600 sur Unix)
Les tokens sont chiffrés au repos (sur certains systèmes)
Rafraîchissement automatique avant l'expiration

Rafraîchissement automatique du token

CLI rafraîchit automatiquement les tokens d'accès :

# Première commande : Token valide
teamday agents list
# Fonctionne immédiatement

# ... 15 minutes plus tard, token expiré ...

# Commande suivante : Token auto-rafraîchi
teamday agents exec char_123 "message"
# CLI détecte l'expiration, rafraîchit le token, puis exécute

Rafraîchissement manuel :

teamday auth refresh

Vérifier le statut de l'authentification

teamday auth status

Sortie :

✓ Authentifié

Utilisateur : [email protected]
Organisation : Acme Corp
Méthode : OAuth
Token d'accès : Valide (expire dans 12 min)
Token de rafraîchissement : Valide (expire dans 85 jours)

Se déconnecter

teamday auth logout

Cela :

Supprime les tokens locaux
Révoque le token d'accès sur le serveur
Nécessite une ré-authentification pour la prochaine commande

Meilleures pratiques de sécurité

1. Ne jamais commit les tokens sur Git

Utilisez .gitignore :

# .gitignore
.env
.env.local
.teamday/
config.json
*_token.txt

Vérifier avant commit :

git diff --cached | grep -i "td_"

2. Utilisez les variables d'environnement

Pour les PATs :

# .env (NE PAS COMMIT)
TEAMDAY_API_TOKEN=td_xxx

# Charger dans les scripts
export $(cat .env | xargs)

En CI/CD :

GitHub Actions : Repository Secrets
GitLab CI : Variables CI/CD
CircleCI : Project Settings → Environment Variables

3. Principe du moindre privilège

Créer des tokens séparés pour différents objectifs :

✓ Bien :
- "CI/CD Deploy" - Utilisé uniquement dans le pipeline de déploiement
- "Daily Reports" - Utilisé uniquement pour les rapports automatisés
- "Development" - Utilisé localement, rotation fréquente

✗ Mal :
- "Master Token" - Utilisé partout (si compromis, accès complet)

4. Définir les dates d'expiration

Pour les tokens d'automation :

Projets à courte durée de vie : 30 jours
CI/CD à long terme : 90 jours
Examen trimestriel : 1 an

Examiner avant l'expiration :

Définir des rappels calendrier
Automatiser les notifications d'expiration
Rotation proactive

5. Surveiller l'utilisation du token

Via l'interface : Paramètres → Clés API → Afficher "Dernière utilisation"

Drapeaux rouges :

Les tokens ne sont jamais utilisés (supprimez-les)
Temps d'utilisation inattendu (enquêter)
Grand volume de requêtes (abus potentiel)

6. Stockage sécurisé des tokens

Développement local :

# Utilisez un gestionnaire de mots de passe
# Exemple : 1Password, LastPass, Bitwarden

# Ou fichier chiffré
gpg --encrypt --recipient [email protected] token.txt
# Déchiffrer quand nécessaire
gpg --decrypt token.txt.gpg

Production :

# Utilisez la gestion des secrets
# AWS : Secrets Manager
# GCP : Secret Manager
# Azure : Key Vault
# Kubernetes : Secrets

7. Rotation régulière

Calendrier recommandé :

Tokens de développement : Mensuellement
Tokens CI/CD : Trimestriellement
Tokens de production : Tous les 6 mois
Sur changements d'équipe : Immédiatement

8. Audit d'accès

Audit mensuel :

# Lister tous les tokens
teamday auth tokens list

# Vérifier chacun :
# - Encore nécessaire ?
# - Le propriétaire est-il toujours dans l'équipe ?
# - Utilisé récemment ?
# - Expiration appropriée ?

# Révoquer les tokens inutiles
teamday auth tokens revoke token_old_id

9. Réponse aux incidents

Si token compromis :

Étape 1 : Révoquer immédiatement

teamday auth tokens revoke token_compromised_id

Étape 2 : Examiner les logs d'audit

teamday audit --token token_compromised_id --since "1 week ago"

Étape 3 : Évaluer les dégâts

Quels agents ont été consultés ?
Quelles données ont été exposées ?
Des actions destructrices ont-elles été prises ?

Étape 4 : Rotation de tous les tokens

Ne sais pas lequel était compromis ? Rotationner tous

Étape 5 : Mettre à jour la documentation

Comment a-t-il été compromis ?
Comment prévenir à l'avenir ?

10. Limitation du débit

Être conscient des limites de taux :

Avec PAT : 1000 requêtes/heure
Avec OAuth : 500 requêtes/heure

Éviter :

# Mauvais : Sondage dans une boucle serrée
while true; do
  teamday agents list
  sleep 1
done

Faire :

# Bon : Sondage raisonnable
while true; do
  teamday agents list
  sleep 60  # Vérifier chaque minute
done

Dépannage

Erreur de token invalide

Symptômes :

Erreur : Token invalide ou expiré
Statut : 401 Non autorisé

Solutions :

Pour PAT :

# Vérifier que le token est correct
echo $TEAMDAY_API_TOKEN

# Vérifier si le token est actif
teamday auth tokens list

# Créer un nouveau token si nécessaire
# (via l'interface : Paramètres → Clés API → Nouveau token)

Pour OAuth :

# Le token a expiré, rafraîchir
teamday auth refresh

# Ou se reconnecter
teamday auth logout
teamday auth login

Accès refusé

Symptômes :

Erreur : Vous n'avez pas la permission de effectuer cette action
Statut : 403 Interdit

Causes :

Le token a des scopes insuffisants (fonctionnalité future)
Le rôle utilisateur ne permet pas l'action
La ressource appartient à une autre organisation

Solutions :

# Vérifier le statut d'authentification
teamday auth status

# Vérifier l'organisation
teamday config get organization

# Changer d'organisation (si membre de plusieurs)
teamday config set organization org_different_id

Token non trouvé

Symptômes :

Erreur : Aucun token d'authentification trouvé

Solutions :

# Vérifier si connecté
teamday auth status

# Si non, se connecter
teamday auth login

# Ou définir le PAT
teamday auth set-key "td_xxx"

# Ou utiliser la variable d'environnement
export TEAMDAY_API_TOKEN="td_xxx"

Flux OAuth se bloque

Symptômes : Le navigateur n'affiche jamais la page de succès

Solutions :

1. Vérifier la console du navigateur pour les erreurs

2. Exécution manuelle :

# Annuler le flux bloqué
Ctrl+C

# Réessayer avec saisie manuelle de code
teamday auth login --manual

3. Utiliser PAT à la place :

# Générer le PAT via l'interface
# Puis définir dans CLI
teamday auth set-key "td_xxx"

Dépassement de la limite de débit

Symptômes :

Erreur : Limite de débit dépassée
Statut : 429 Trop de requêtes
Retry-After : 3600

Solutions :

# Attendre la réinitialisation du limite de débit (1 heure)

# Ou implémenter l'exponentielle backoff
#!/bin/bash
retry=0
max_retries=5
while [ $retry -lt $max_retries ]; do
  if teamday agents list; then
    exit 0
  fi
  wait=$((2 ** retry))
  echo "Réessayer dans ${wait}s..."
  sleep $wait
  retry=$((retry + 1))
done

Prochaines étapes

Utiliser les tokens avec l'Outil CLI
Intégrer avec l'API
Configurer L'automation CI/CD
Apprendre les Meilleures pratiques API