> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taap.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentification

> Apprenez à vous authentifier avec l'API taap.it en utilisant les clés API

L'API taap.it utilise l'authentification basée sur les clés API pour sécuriser l'accès à votre compte et ressources. Toutes les requêtes API doivent inclure une clé API valide dans l'en-tête Authorization.

## Aperçu des clés API

Les clés API fournissent un accès sécurisé à votre compte taap.it et sont créées via le tableau de bord de l'application web. Chaque clé API est :

* **Spécifique à l'utilisateur** : Liée à votre compte utilisateur
* **À portée définie** : Peut avoir un accès complet, en lecture seule, ou des permissions limitées
* **Sécurisée** : Préfixée avec `taapit_` et générée cryptographiquement

## Créer des clés API

<Steps>
  <Step title="Accéder aux paramètres API">
    Connectez-vous à votre tableau de bord taap.it et naviguez vers vos paramètres utilisateur.
  </Step>

  <Step title="Générer une nouvelle clé">
    Dans la section "Clés API", cliquez sur "Créer une clé API" et fournissez un nom descriptif.
  </Step>

  <Step title="Définir les permissions">
    Choisissez le niveau de permission approprié pour votre cas d'usage :

    * **Accès complet** : Accès complet en lecture/écriture à toutes les ressources
    * **Lecture seule** : Accès en vue seule à toutes les ressources
    * **Accès limité** : Permissions personnalisées pour des ressources spécifiques
  </Step>

  <Step title="Stocker en sécurité">
    Copiez la clé API générée immédiatement et stockez-la en sécurité.

    <Warning>
      Les clés API ne sont affichées qu'une seule fois lors de la création. Si perdue, vous devrez générer une nouvelle clé.
    </Warning>
  </Step>
</Steps>

## Utiliser les clés API

Incluez votre clé API dans l'en-tête Authorization en utilisant le format Bearer token :

```http theme={null}
Authorization: Bearer taapit_votre_cle_api_ici
```

### Exemples de requêtes

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.taap.it/v1/workspaces' \
    -H 'Authorization: Bearer taapit_abc123def456ghi789' \
    -H 'Content-Type: application/json'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.taap.it/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': f'Bearer {api_key}',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.taap.it/v1/workspaces', headers=headers)
  ```

  ```php PHP theme={null}
  <?php
  $headers = [
      'Authorization: Bearer ' . $api_key,
      'Content-Type: application/json'
  ];

  $response = file_get_contents('https://api.taap.it/v1/workspaces', false, 
      stream_context_create(['http' => ['header' => implode("\r\n", $headers)]])
  );
  ?>
  ```
</CodeGroup>

## Niveaux de permissions

Les clés API peuvent avoir différents niveaux de permissions qui contrôlent l'accès aux ressources :

### Accès complet

<Check>
  Accorde un accès complet en lecture et écriture à toutes les ressources et endpoints.
</Check>

* **Cas d'usage** : Intégrations serveur-à-serveur, outils administratifs
* **Permissions** : Toutes les opérations de lecture et écriture
* **Sécurité** : Élevée - surveillez l'usage attentivement

### Lecture seule

<Info>
  Fournit un accès en vue seule à toutes les ressources sans capacités de modification.
</Info>

* **Cas d'usage** : Tableaux de bord d'analyses, outils de reporting
* **Permissions** : Opérations GET uniquement
* **Sécurité** : Moyenne - exposition de données limitée à la visualisation

### Accès limité

<Tip>
  Les permissions personnalisées permettent un contrôle granulaire sur des ressources et opérations spécifiques.
</Tip>

* **Cas d'usage** : Intégrations tierces avec besoins spécifiques
* **Permissions** : Configurable par ressource (domaines, liens, projets, espaces de travail, analyses)
* **Sécurité** : Élevée - permissions minimales nécessaires

## Gestion des clés API

### Voir les clés API

Vous pouvez lister toutes vos clés API pour surveiller l'usage :

**Requête :**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/api-keys' \
  -H 'Authorization: Bearer taapit_votre_cle_api_ici'
```

**Réponse :**

```json theme={null}
[
  {
    "id": "ak_123456789",
    "name": "Intégration Production",
    "key": "taapit_abc123***",
    "is_active": true,
    "access_full": true,
    "access_read_only": false,
    "access_limited": false,
    "created_at": "2024-01-15T10:30:00Z"
  }
]
```

### Valider les clés API

Testez si votre clé API est valide :

**Requête :**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/api-keys/validate' \
  -H 'Authorization: Bearer taapit_votre_cle_api_ici'
```

**Réponse :**

```json theme={null}
{
  "valid": true,
  "user_id": "user_123456789",
  "permissions": {
    "domains": "write",
    "links": "write",
    "projects": "write",
    "workspaces": "write",
    "analytics": "read"
  }
}
```

### Désactiver les clés API

Si une clé API est compromise ou n'est plus nécessaire, désactivez-la :

**Requête :**

```bash cURL theme={null}
curl -X DELETE 'https://api.taap.it/v1/api-keys/ak_123456789' \
  -H 'Authorization: Bearer taapit_votre_cle_api_ici'
```

**Réponse :**

```json theme={null}
{
  "message": "Clé API désactivée avec succès"
}
```

## Meilleures pratiques de sécurité

<AccordionGroup>
  <Accordion title="Stockage des clés">
    * Stockez les clés API dans des variables d'environnement, pas dans le code
    * Utilisez des services de gestion de clés sécurisés pour la production
    * Ne commitez jamais les clés API dans le contrôle de version
    * Faites une rotation régulière des clés pour une sécurité renforcée
  </Accordion>

  <Accordion title="Contrôle d'accès">
    * Utilisez le principe du moindre privilège
    * Créez des clés séparées pour différents environnements
    * Surveillez l'usage des clés API et configurez des alertes
    * Désactivez immédiatement les clés inutilisées ou compromises
  </Accordion>

  <Accordion title="Sécurité réseau">
    * Utilisez toujours HTTPS pour les requêtes API
    * Implémentez une gestion d'erreurs appropriée
    * Utilisez la liste blanche IP quand possible
    * Surveillez les activités suspectes
  </Accordion>
</AccordionGroup>

## Gestion d'erreurs

### Erreurs d'authentification

**401 Non autorisé :**

```json theme={null}
{
  "detail": "Clé API invalide"
}
```

**403 Interdit :**

```json theme={null}
{
  "detail": "Permissions insuffisantes pour cette opération"
}
```

### Problèmes d'authentification courants

<AccordionGroup>
  <Accordion title="Clé API invalide">
    * Vérifiez que la clé est copiée correctement
    * Vérifiez que la clé n'a pas été désactivée
    * Assurez-vous d'utiliser la clé complète incluant le préfixe `taapit_`
  </Accordion>

  <Accordion title="Permission refusée">
    * Vérifiez si votre clé API a les permissions requises
    * Vérifiez que vous essayez d'accéder aux ressources que vous possédez
    * Considérez la mise à niveau vers une clé avec accès complet
  </Accordion>

  <Accordion title="Limitation de taux">
    * Surveillez votre fréquence de requêtes
    * Implémentez un backoff exponentiel
    * Vérifiez les en-têtes de limite de taux dans les réponses
  </Accordion>
</AccordionGroup>

<Card title="Prêt à vous authentifier ?" icon="key" href="/fr/quickstart">
  Suivez notre guide de démarrage rapide pour faire votre premier appel API authentifié.
</Card>