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

# Authentification

> Méthodes d'authentification API, gestion des clés et meilleures pratiques de sécurité.

Truthlocks prend en charge plusieurs méthodes d'authentification pour sécuriser l'accès à l'API. Ce guide couvre les clés API, les jetons JWT et les meilleures pratiques de sécurité.

## Méthodes d'authentification

> [card] Clés API
>
> Identifiants de longue durée pour la communication de serveur à serveur. Recommandé pour
> services backend.

> [card] Jetons du porteur (JWT)
>
> Jetons de courte durée pour les utilisateurs authentifiés. Idéal pour les applications frontend
> et le contexte utilisateur.

## Clés API

Truthlocks propose deux types de clés API selon la façon dont vous utilisez la plateforme :

| Type | Préfixe | Créé à partir de | Cas d'utilisation |
| :- | :- | :- | :- |
| **Clé de locataire** | `tl_live_` / `tl_test_` | [Console](https://console.truthlocks.com) | Intégrations serveur à serveur, flux de travail d'entreprise |
| **Clé consommateur** | `tlk_` | [Portail Verify](https://verify.truthlocks.com) | Accès API personnel pour la protection et la vérification du contenu |

### Transmission de votre clé

Incluez votre clé API en utilisant l'un de ces en-têtes :

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "X-API-Key: tl_live_your_api_key"
```

Vous pouvez également utiliser l'en-tête `Authorization` avec le schéma `ApiKey` :

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "Authorization: ApiKey tl_live_your_api_key"
```

Ces formats authentifient les points de terminaison activés par clé API. Certaines opérations nécessitent un jeton de porteur utilisateur et des vérifications de rôle ; les points de terminaison de santé publique n'en ont pas besoin. `X-API-Key` est plus courant dans les exemples de cette documentation.

## Clés API du locataire

Les clés de locataire sont la méthode d'authentification principale pour les organisations utilisant Truthlocks. Elles sont limitées à un locataire et prennent en charge des permissions granulaires.

### Structure de clé

```text theme={null}
tl_live_abc123def456gh789ijklmnopqrstuv
│  │    │
│  │    └── 32-character random identifier
│  └── Environment: test | live
└── Prefix: tl (Truthlocks)
```

### Portées

Les clés API du locataire peuvent être restreintes à des permissions spécifiques :

| Portée | Permissions |
| - | - |
| `attestations:mint` | Créer de nouvelles attestations |
| `attestations:read` | Lire les détails de l'attestation et les paquets de preuves |
| `attestations:revoke` | Révoquer les attestations |
| `issuers:read` | Afficher les informations de l'émetteur |
| `issuers:write` | Créer et gérer les émetteurs |
| `users:read` | Afficher les utilisateurs et les rôles |
| `users:write` | Inviter des utilisateurs, gérer les rôles |
| `audit:read` | Consulter les journaux d'audit |

> [!NOTE]
>
> **Principe du moindre privilège :** N'accordez que les portées dont votre application a besoin
> a réellement besoin. Une clé avec `attestations:mint` seulement ne devrait pas avoir également
> `users:write`.

### Création d'une clé de locataire

#### Via la console

1. Naviguez vers [console.truthlocks.com/api-keys](https://console.truthlocks.com/api-keys)
2. Cliquez sur « Créer une clé API »
3. Entrez un nom descriptif (par exemple, "Backend de production")
4. Sélectionnez l'environnement (production ou sandbox) et les portées requises
5. Copiez la clé immédiatement — elle ne sera plus affichée

#### Via l'API

```bash Request theme={null}
curl -X POST https://api.truthlocks.com/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "scopes": ["attestations:mint", "attestations:read", "issuers:read"]
  }'
```

```json Response theme={null}
{
  "id": "key-uuid",
  "name": "Production Backend",
  "prefix": "tl_live_abc",
  "secret": "tl_live_abc123def456gh789ijklmnopqrstuv",
  "scopes": ["attestations:mint", "attestations:read", "issuers:read"],
  "created_at": "2026-01-13T12:00:00Z"
}
```

> [!WARNING]
>
> **Critique :** Le champ `secret` n'est renvoyé qu'une seule fois lors de la création. Stockez-le
> immédiatement dans un gestionnaire de secrets.

## Clés API du consommateur

Les clés de consommateur permettent aux utilisateurs individuels d'accéder aux API de protection et de vérification par programmation — par exemple, pour créer des attestations à partir d'un pipeline CI ou intégrer la protection de contenu dans vos propres outils.

### Détails clés

* Chaque compte prend en charge jusqu'à **5 clés actives**.
* Les clés expirent automatiquement après **90 jours**.
* Les clés révoquées ou expirées ne peuvent pas être réactivées — créez-en une nouvelle à la place.

### Portées fixes

Les clés de consommateur sont émises avec un ensemble fixe de portées qui ne peuvent pas être personnalisées :

| Portée | Permissions |
| :- | :- |
| `consumer:read` | Lire votre profil et vos paramètres de consommateur |
| `consumer:write` | Mettre à jour votre profil et vos paramètres de consommateur |
| `attestations:mint` | Émettre de nouvelles attestations |
| `attestations:read` | Lire vos attestations |
| `verify:read` | Vérifier les attestations |

### Création d'une clé consommateur

**1. Ouvrir les paramètres**

Dans la barre latérale du portail de vérification, allez dans **Paramètres > Clés API**.

**2. Créer une clé**

Cliquez sur **Créer une clé API**, entrez un nom descriptif et confirmez. Le plein
le secret est affiché une seule fois — copiez-le et stockez-le en toute sécurité.

**3. Utiliser la clé**

Passez la clé dans l'en-tête `X-API-Key` avec chaque requête :

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/consumer/protections \
  -H "X-API-Key: tlk_your_key_here"
```

Pour plus de détails sur la gestion des clés de consommateur, consultez le [guide du portail consommateur](https://docs.truthlocks.com/fr/guides/consumer-portal.md#api-keys).

## Jetons Bearer (JWT)

Les jetons JWT sont utilisés lorsque vous devez effectuer des appels API au nom d'un utilisateur authentifié, par exemple à partir d'une application web ou mobile.

### Utilisation des jetons Bearer

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
```

### Structure du jeton

```json theme={null}
{
  "sub": "user-uuid",
  "tenant_id": "tenant-uuid",
  "email": "user@example.com",
  "roles": ["admin"],
  "iat": 1705147200,
  "exp": 1705150800,
  "iss": "https://auth.truthlocks.com"
}
```

### Durée de vie du jeton

| Type de jeton | Durée de vie | Actualisation |
| - | - | - |
| Jeton d'accès | 1 heure | Via jeton de rafraîchissement |
| Jeton d'actualisation | 30 jours | Via réauthentification |

## Authentificateur MFA pour les comptes Console

Dans la Console, ouvrez **Paramètres → Sécurité → Authentificateur MFA** pour connecter Google Authenticator ou une autre application d'authentification basée sur le temps.

1. Confirmez votre mot de passe Truthlocks local actuel.
2. Scannez le code QR privé, ou entrez la clé de configuration dans votre authentificateur comme un compte basé sur le temps.
3. Entrez le code à six chiffres de l'application pour activer l'AMF.
4. Enregistrez les dix codes de récupération affichés après confirmation. Ils sont affichés une seule fois, et chaque code fonctionne une fois.

Les nouvelles connexions nécessitent le deuxième facteur après votre mot de passe ou votre fournisseur d'identité d'entreprise. L'étape de vérification expire après cinq minutes. Des codes incorrects répétés bloquent temporairement la vérification pour le compte. Un code déjà accepté ne peut pas être réutilisé.

Pour remplacer les codes de récupération ou désactiver l'AMF, confirmez votre mot de passe et un nouveau code d'authentification ou un code de récupération inutilisé. Le remplacement des codes de récupération invalide l'ensemble précédent. Les utilisateurs SSO qui n'ont jamais défini de mot de passe Truthlocks local peuvent utiliser le flux de réinitialisation de mot de passe pour leur e-mail enregistré avant l'inscription.

L'inscription à l'AMF s'applique à votre propre compte. Elle n'inscrit pas d'autres membres et n'impose pas d'exigence d'AMF à l'échelle de l'espace de travail. L'activation de l'AMF ne révoque pas automatiquement les sessions existantes. Les clés API restent des identifiants système distincts.

## Meilleures pratiques de sécurité

> [card] ✅ Utiliser la gestion des secrets
>
> Stockez les clés API dans Google Secret Manager, HashiCorp Vault ou similaire. Jamais
> coder en dur les clés dans le code de l'application.

> [card] ✅ Faire pivoter les clés régulièrement
>
> Créez de nouvelles clés et révoquez les anciennes périodiquement. Utilisez des noms descriptifs avec
> dates (par exemple, "Backend-2026-Q1").

> [card] ✅ Restreindre les portées
>
> N'accordez que les autorisations réellement nécessaires. Examinez et auditez les portées des clés
> régulièrement.

> [card] ❌ Ne jamais exposer en frontend
>
> Les clés API ne doivent jamais être incluses dans le JavaScript côté client. Utilisez des jetons JWT
> pour l'authentification frontend.

> [card] ❌ Ne jamais commettre sur Git
>
> Utilisez des variables d'environnement ou la gestion des secrets. Ajoutez `.env*` à
> `.gitignore`.

## Prochaines étapes

> [card] [Portail consommateur](https://docs.truthlocks.com/guides/consumer-portal.md)
>
> Gérez les clés API des consommateurs, les protections et les paramètres.

> [card] [Environnements](https://docs.truthlocks.com/environments.md)
>
> Configuration Sandbox vs. production et URL de base.

> [card] [RBAC et autorisations](https://docs.truthlocks.com/security/rbac.md)
>
> Comprendre les rôles, les permissions et le contrôle d'accès.

> [card] [Journaux d'audit](https://docs.truthlocks.com/security/audit.md)
>
> Suivez toutes les activités API et les événements de sécurité.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.