Jetons d'accès personnels

Les jetons d'accès personnels (PAT) permettent un accès programmatique à l'API TeamDay pour l'automation, les pipelines CI/CD et l'authentification d'agents.

Démarrage rapide

1. Créer votre jeton

Naviguez vers Paramètres → Profil
Descendez jusqu'à Jetons d'accès personnels
Cliquez sur Créer un jeton
Donnez-lui un nom descriptif (par ex., "Pipeline CI", "Automation de production")
Choisissez une période d'expiration (90 jours recommandé)
Copiez le jeton immédiatement - il ne sera affiché qu'une seule fois !

2. Utiliser votre jeton

Incluez votre jeton dans l'en-tête Authorization :

curl -H "Authorization: Bearer td_votre-jeton-ici" \
     https://teamday.ai/api/v1/agents

Ou définissez-le comme variable d'environnement :

export TEAMDAY_TOKEN="td_votre-jeton-ici"

curl -H "Authorization: Bearer $TEAMDAY_TOKEN" \
     https://teamday.ai/api/v1/agents

Bonnes pratiques de sécurité

:::warning Directives de sécurité importantes

Ne jamais committer les jetons dans le contrôle de version - Utiliser des variables d'environnement ou des gestionnaires de secrets
Faire tourner les jetons régulièrement - Définir des dates d'expiration appropriées
Utiliser des jetons séparés par intégration - Facilite la révocation
Nommer les jetons de manière descriptive - Savoir où chaque jeton est utilisé
Révoquer les jetons inutilisés immédiatement - Réduire la surface de sécurité
Ne jamais partager les jetons - Chaque membre de l'équipe devrait avoir le sien :::

Recommandations de stockage

✅ Stockage sécurisé :

Variables d'environnement : export TEAMDAY_TOKEN="..."
Gestionnaires de secrets : AWS Secrets Manager, HashiCorp Vault, 1Password
Secrets CI/CD : GitHub Secrets, variables CI/CD GitLab
Fichiers .env (avec .gitignore)

❌ Stockage non sécurisé :

Codé en dur dans le code source
Committé dans les dépôts git
Partagé via Slack/email
Stocké dans des fichiers texte brut dans des lecteurs partagés

Portées et permissions des jetons

Les jetons d'accès personnels ont les mêmes permissions que l'utilisateur qui les a créés :

Accès à l'organisation : Le jeton est limité à votre organisation actuelle
Permissions utilisateur : Hérite des permissions de votre rôle (admin, membre, spectateur)
Accès aux ressources : Peut accéder à toutes les ressources auxquelles vous pouvez accéder via l'interface
Ressources privées : Accès à vos agents, espaces et chats privés

Endpoints API avec PAT

Une fois authentifié, vous pouvez accéder à ces endpoints :

Agents

# Lister tous les agents
GET /api/v1/agents

# Créer un agent
POST /api/v1/agents

# Obtenir les détails d'un agent
GET /api/v1/agents/{agentId}

# Mettre à jour un agent
PATCH /api/v1/agents/{agentId}

# Supprimer un agent
DELETE /api/v1/agents/{agentId}

# Exécuter un agent
POST /api/v1/agents/{agentId}/execute

Tâches

# Lister les tâches
GET /api/v1/tasks

# Créer une tâche
POST /api/v1/tasks

# Obtenir les détails d'une tâche
GET /api/v1/tasks/{taskId}

# Mettre à jour une tâche
PATCH /api/v1/tasks/{taskId}

Exécutions

# Lister les exécutions
GET /api/v1/executions

# Obtenir les détails d'une exécution
GET /api/v1/executions/{executionId}

# Obtenir l'arbre d'exécution (avec délégations)
GET /api/v1/executions/{executionId}/tree

# Annuler une exécution
POST /api/v1/executions/{executionId}/cancel

Espaces (Opérations sur les fichiers)

# Parcourir les fichiers
GET /api/spaces/{spaceId}/files/browse?path={path}

# Lire un fichier
GET /api/spaces/{spaceId}/files/read?path={path}

# Écrire un fichier
POST /api/spaces/{spaceId}/files/write

# Télécharger un fichier
POST /api/spaces/{spaceId}/files/upload

Consultez notre Référence API pour la documentation complète des endpoints.

Exemple : Créer et exécuter un agent

const TEAMDAY_TOKEN = process.env.TEAMDAY_TOKEN!

// 1. Créer un agent
const agent = await fetch('https://teamday.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TEAMDAY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Réviseur de code',
    role: 'Développeur senior',
    systemPrompt: 'Vous examinez le code pour la qualité, la sécurité et les bonnes pratiques.',
    visibility: 'organization',
  }),
}).then(r => r.json())

console.log(`Agent créé : ${agent.id}`)

// 2. Exécuter l'agent
const execution = await fetch(`https://teamday.ai/api/v1/agents/${agent.id}/execute`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TEAMDAY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Examiner le code d\'authentification dans src/auth.ts',
    spaceId: 'space_votre-espace-de-travail',
    stream: false, // Obtenir la réponse complète une fois terminée
  }),
}).then(r => r.json())

console.log(`Examen terminé :`, execution.messages)

Utiliser les jetons dans CI/CD

GitHub Actions

name: Déployer avec l'agent TeamDay

on:
  push:
    branches: [main]

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

      - name: Déployer via l'agent TeamDay
        env:
          TEAMDAY_TOKEN: ${{ secrets.TEAMDAY_TOKEN }}
        run: |
          curl -X POST https://teamday.ai/api/v1/agents/char_deploy_bot/execute \
            -H "Authorization: Bearer $TEAMDAY_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{
              "message": "Déployer le commit ${{ github.sha }} en production",
              "spaceId": "space_production",
              "stream": false
            }'

GitLab CI

deploy:
  stage: deploy
  script:
    - |
      curl -X POST https://teamday.ai/api/v1/agents/${AGENT_ID}/execute \
        -H "Authorization: Bearer ${TEAMDAY_TOKEN}" \
        -H "Content-Type: application/json" \
        -d "{\"message\": \"Déployer ${CI_COMMIT_SHA}\"}"
  only:
    - main

Utiliser les jetons dans les environnements virtuels

Lors de l'utilisation d'agents dans des environnements virtuels isolés (comme les conteneurs Docker ou les fonctions cloud), passez le jeton comme variable d'environnement :

# Dans Paramètres d'espace → Variables d'environnement
TEAMDAY_TOKEN=td_votre-jeton-ici

Votre agent peut ensuite utiliser ce jeton pour appeler d'autres API TeamDay ou déléguer du travail à d'autres agents.

Gestion des jetons

Afficher vos jetons

Allez dans Paramètres → Profil → Jetons d'accès personnels pour voir :

Nom du jeton et date de création
Horodatage de dernière utilisation
Date d'expiration
Valeur du jeton masquée (pour identification)

Révoquer les jetons

Cliquez sur l'icône poubelle à côté de n'importe quel jeton pour le révoquer immédiatement. Cela va :

Invalider le jeton de manière permanente
Arrêter toutes les requêtes API utilisant ce jeton
Supprimer le jeton de votre compte

:::warning Avertissement Révoquer un jeton cassera tous les scripts, pipelines CI/CD ou intégrations l'utilisant. Assurez-vous de mettre à jour ces systèmes avant de révoquer. :::

Expiration du jeton

Les jetons expirent automatiquement selon la période d'expiration que vous avez sélectionnée :

7 jours - Pour les tests et l'utilisation à court terme
30 jours - Pour l'automation mensuelle
90 jours - Recommandé pour l'utilisation en production
180 jours - Pour les intégrations de longue durée
365 jours - Expiration maximale (nécessite une gestion de sécurité minutieuse)

Vous devrez créer un nouveau jeton lorsque l'ancien expire.

Limites de débit

:::tip Limites de débit actuelles

Création de jeton : 10 jetons par heure par utilisateur
Requêtes API : 1 000 requêtes par minute par jeton
Exécution d'agent : 100 exécutions simultanées par organisation :::

Si vous atteignez les limites de débit, vous recevrez une réponse 429 Too Many Requests. Implémentez un backoff exponentiel dans vos scripts d'automation.

Gestion des erreurs

Gérez toujours les erreurs d'authentification avec élégance :

async function callTeamDayAPI(endpoint: string, options: RequestInit) {
  const response = await fetch(`https://teamday.ai${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  })

  if (response.status === 401) {
    throw new Error('Jeton invalide ou expiré. Créez un nouveau jeton dans Paramètres → Profil.')
  }

  if (response.status === 403) {
    throw new Error('Le jeton n\'a pas la permission pour cette opération.')
  }

  if (response.status === 429) {
    throw new Error('Limite de débit dépassée. Veuillez réessayer après un délai.')
  }

  if (!response.ok) {
    const error = await response.json().catch(() => ({ message: response.statusText }))
    throw new Error(`Erreur API TeamDay : ${error.message}`)
  }

  return response.json()
}

Migration d'OAuth vers PAT

Si vous utilisez actuellement des jetons OAuth du CLI, envisagez de migrer vers les jetons d'accès personnels :

OAuth (CLI) :

✅ Flux d'authentification interactif
✅ Rafraîchissement automatique du jeton
❌ Nécessite un navigateur pour l'authentification initiale
❌ Les jetons expirent (15 min d'accès, 90 jours de rafraîchissement)

Jetons d'accès personnels :

✅ Longue durée de vie (jusqu'à 1 an)
✅ Pas de navigateur requis
✅ Parfait pour l'automation côté serveur
❌ Gestion manuelle des jetons
❌ Pas de rafraîchissement automatique

Choisir les PAT pour :

Pipelines CI/CD
Automation côté serveur
Conteneurs Docker
Fonctions cloud
Tâches cron

Choisir OAuth pour :

Utilisation interactive du CLI
Développement local
Applications desktop

Dépannage

Erreur "Jeton invalide"

Causes possibles :

Le jeton a expiré
Le jeton a été révoqué
Le jeton a été copié incorrectement (préfixe ou caractères manquants)

Solution : Créez un nouveau jeton et mettez à jour vos variables d'environnement.

Erreur "Interdit"

Causes possibles :

Votre compte n'a pas la permission pour l'opération demandée
Le jeton provient d'une autre organisation

Solution : Vérifiez votre appartenance à l'organisation et les permissions de rôle.

Le jeton ne fonctionne pas dans les requêtes

Liste de vérification :

✅ Inclure le jeton complet avec le préfixe td_
✅ Utiliser l'en-tête Authorization: Bearer (pas seulement Authorization)
✅ Pas d'espaces ou de retours à la ligne supplémentaires dans la valeur du jeton
✅ Le jeton n'a pas expiré
✅ Le jeton appartient à la bonne organisation

Documentation associée

Référence API - Documentation complète des endpoints API
Architecture d'authentification - Aperçu de toutes les méthodes d'authentification
Guide de l'outil CLI - Utilisation du CLI TeamDay
Automation de workflow - Construction de workflows automatisés

Besoin d'aide ?

Si vous rencontrez des problèmes avec les jetons d'accès personnels :

Consultez notre Guide de dépannage
Contactez le support à [email protected]
Signalez des bugs sur Problèmes GitHub