> ## 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.

# Concepts fondamentaux

> Comprendre les locataires, les émetteurs, les attestations et la vérification.

Ce guide explique les éléments fondamentaux de la plateforme Truthlocks. Comprendre ces concepts est essentiel pour une intégration efficace.

## Locataires

Un **locataire** est l'unité organisationnelle de niveau supérieur dans Truthlocks. Chaque locataire représente un client ou une organisation distincte avec une isolation complète des données.

| Propriété | Description |
| - | - |
| `id` | UUID unique identifiant le locataire |
| `name` | Nom d'organisation lisible par l'homme |
| `slug` | Identifiant sûr pour URL (par exemple, `acme-corp`) |
| `tier` | Niveau d'abonnement : GRATUIT, STARTER, PROFESSIONNEL, ENTREPRISE |
| `status` | ACTIF, SUSPENDU ou SUPPRIMÉ |

### Contrôles multi-locataires

* **Isolation des données :** Les données de chaque locataire sont complètement isolées au niveau de la base de données
* **Limites de ressources:** Les limites de débit et les quotas sont appliqués par locataire
* **Portée des clés API :** Les clés API sont liées à un seul locataire et ne peuvent pas accéder aux données d'autres locataires
* **Séparation d'audit :** Les journaux d'audit sont partitionnés par locataire

## Émetteurs

Un **émetteur** est une entité qui peut créer et signer des attestations. Les émetteurs représentent des organisations, des institutions ou des services qui font des revendications sur des sujets.

> [card] Identité
>
> Chaque émetteur a un domaine vérifié (par exemple, `acme.edu`) qui établit son
> identité réelle.

> [card] Clés cryptographiques
>
> Les émetteurs enregistrent les clés publiques Ed25519 utilisées pour vérifier les signatures d'attestation.

> [card] Statut de confiance
>
> Les nouveaux émetteurs sont activés immédiatement lors de leur création. Les niveaux de confiance supérieurs nécessitent un examen de la demande : ACTIF → SUSPENDU.

> [card] Niveau de confiance
>
> BASIC, VERIFIED ou PREMIUM en fonction de la profondeur de la vérification d'identité.

### Cycle de vie de l'émetteur

```text theme={null}
                    ┌──────────────┐
                    │   CREATED    │
                    └───────┬──────┘
                            │ auto-activated
                            ▼
                    ┌──────────────┐
                    │    ACTIVE    │  ← Ready to mint (BASIC trust)
                    └───────┬──────┘
                            │
            suspend │               │ apply for higher tier
                    ▼               ▼
            ┌──────────────┐  ┌──────────────┐
            │   SUSPENDED  │  │   IN REVIEW  │
            └──────────────┘  └───────┬──────┘
                                      │
                              approve │ reject
                              ▼               ▼
                      ┌──────────────┐  ┌──────────────┐
                      │    ACTIVE    │  │   REJECTED   │
                      │ (higher tier)│  │ (keeps BASIC)│
                      └──────────────┘  └──────────────┘
```

> [!NOTE]
>
> Les nouveaux émetteurs sont activés immédiatement avec le niveau de confiance **Basique**. Aucune approbation manuelle n'est requise pour commencer à émettre des attestations. Pour passer à un niveau de confiance supérieur (Organisation vérifiée, Entité gouvernementale ou Institution accréditée), soumettez une [demande d'émetteur](https://docs.truthlocks.com/fr/guides/issuer-applications.md) pour examen.

## Attestations

Une **attestation** est une revendication signée cryptographiquement faite par un émetteur à propos d'un sujet. Les attestations sont le primitif central du système Truthlocks.

### Structure d'attestation

```json theme={null}
{
  "id": "uuid", // Unique identifier
  "issuer_id": "uuid", // Who signed it
  "kid": "string", // Key used to sign
  "status": "VALID", // Current status
  "payload": {
    "subject": "string", // Who/what the claim is about
    "claim": "string", // Type of claim (e.g., "verified_email")
    "value": "any", // The actual claim data
    "metadata": {} // Optional additional data
  },
  "signature": "base64", // Ed25519 signature
  "log_index": 42, // Position in transparency log
  "created_at": "datetime"
}
```

### Propriétés d'attestation

| Propriété | Description |
| - | - |
| **Immuable** | Une fois créés, la charge utile et la signature ne peuvent pas être modifiées |
| **Révoquable** | Les émetteurs peuvent révoquer les attestations, mettant à jour le statut à RÉVOQUÉ |
| **Substituable** | Les émetteurs peuvent [substituer](https://docs.truthlocks.com/fr/api-reference/attestations/supersede.md) une attestation par une nouvelle version, créant une chaîne auditable tout en préservant l'original |
| **Portable** | L'ID d'attestation peut être partagé et vérifié n'importe où |
| **Auditable** | Chaque opération est enregistrée dans le journal de transparence |

## Protections des consommateurs

Une **protection du consommateur** est une attestation créée via le flux simplifié [consumer mint](https://docs.truthlocks.com/fr/api-reference/consumer/mint.md), conçu pour les créateurs individuels. Vous hachez votre fichier côté client (SHA-256) et soumettez le hachage avec des métadonnées telles que le titre, la catégorie et le type de contenu. Truthlocks provisionne automatiquement votre identité de signature lors de la première utilisation.

La réponse de frappe du consommateur comprend :

| Champ | Description |
| - | - |
| `protection_id` | ID unique de l'enregistrement de protection |
| `attestation_id` | L'ID d'attestation sous-jacent (utilisé pour la vérification) |
| `content_hash` | Le hachage SHA-256 que vous avez soumis, renvoyé pour confirmation |
| `protected_at` | Horodatage exact de la protection du contenu |
| `verify_url` | URL de la page de preuve publique que vous pouvez partager avec n'importe qui |
| `status` | Statut de confirmation (`protected`) |

Chaque protection génère une page de preuve publique. N'importe qui peut récupérer les métadonnées de la page de preuve via `GET /v1/public/proof/{attestation_id}` — aucune authentification n'est requise. Ce point de terminaison est conçu pour le rendu des pages de preuve et la génération d'aperçus de liens Open Graph pour les URL partagées. Voir le [point de terminaison des métadonnées de preuve](https://docs.truthlocks.com/fr/api-reference/consumer/proof-metadata.md) pour plus de détails.

## Signaux de risque

Un **signal de risque** est une observation notée provenant d'une source de détection de fraude — empreinte digitale de l'appareil, réputation IP, vérification d'e-mail, analyse de documents ou votre propre moteur de règles. Vous pouvez ingérer des signaux directement via l'API, ou soumettre des événements d'identité bruts et laisser la plateforme les normaliser automatiquement en signaux.

Chaque signal comprend :

| Champ | Description |
| :- | :- |
| `signal_source` | D'où provient le signal (par exemple `device_fingerprint`, `ip_reputation`, `login`) |
| `signal_type` | Ce qui a été détecté (par exemple `velocity`, `geo_anomaly`, `ato`, `deepfake`) |
| `risk_score` | Score de risque de `0` (sûr) à `100` (risque élevé) — les scores égaux ou supérieurs à 80 déclenchent une révision automatique |
| `subject_id` | Identifiant de l'entité évaluée |
| `subject_type` | Le type d'entité : `user`, `issuer`, `session`, `device`, `ip`, ou `attestation` |
| `payload` | Métadonnées arbitraires (adresses IP, géolocalisation, raisons) |

### Normalisation des événements

Au lieu de construire manuellement des signaux de risque, vous pouvez soumettre des événements d'identité bruts — échecs de connexion, signatures invalides, suspects de deepfake — à `POST /v1/risk/events`. La plateforme mappe automatiquement chaque événement à un type de signal canonique et à un score de risque de base. Consultez la [référence de l'API de normalisation des événements d'identité](https://docs.truthlocks.com/fr/api-reference/risk/normalize-event.md).

Les signaux de risque sont entièrement isolés par locataire à l'aide de la [sécurité au niveau des lignes](https://docs.truthlocks.com/fr/security/rls.md) et constituent la base du pare-feu d'identité anti-fraude. Consultez le [guide des signaux de risque](https://docs.truthlocks.com/fr/guides/risk-signals.md) pour les détails d'intégration.

## Agents machine

Un **agent machine** est un agent IA, un bot ou un service automatisé enregistré avec le [Protocole d'identité d'agent machine (MAIP)](https://docs.truthlocks.com/fr/guides/machine-identity.md). Chaque agent reçoit un identifiant unique (`maip-agent:<ulid>`) et une paire de clés Ed25519 pour signer les reçus.

| Champ | Description |
| :- | :- |
| `agent_id` | Identifiant MAIP unique pour l'agent |
| `name` | Nom d'agent lisible par l'humain (par exemple, `order-processor`) |
| `type` | Type d'agent : `autonomous`, `supervised`, `delegated`, ou `system` |
| `scopes` | Portées de permission que l'agent est autorisé à utiliser |
| `status` | Statut du cycle de vie : `active`, `suspended`, ou `revoked` |
| `trust_score` | Score de confiance comportemental continu de 0 à 100 |

Les agents opèrent au sein de **sessions** — des contextes d'exécution de courte durée, liés à une portée et avec expiration automatique. Chaque action qu'un agent entreprend génère un **reçu** signé cryptographiquement qui s'enchaîne au reçu précédent pour des pistes d'audit infalsifiables. Neuf types de reçus couvrent le cycle de vie complet de l'agent : genèse, délégation, action, révocation, attestation de données, attestation de modèle, conformité, revendication de vérité et vérification.

Consultez le [guide d'identité machine](https://docs.truthlocks.com/fr/guides/machine-identity.md) pour la configuration et le [guide d'autorisation d'agent](https://docs.truthlocks.com/fr/guides/agent-authorization.md) pour le modèle de portée et de session.

## Lots de preuves

Un **bundle de preuves** est un paquet autonome qui inclut tout le nécessaire pour vérifier une attestation hors ligne, sans contacter les serveurs Truthlocks.

```json theme={null}
{
  "attestation": { ... },       // Full attestation object
  "issuer": {
    "id": "uuid",
    "name": "Acme University",
    "domain": "acme.edu",
    "trust_level": "VERIFIED"
  },
  "public_key": {
    "kid": "ed-key-2026",
    "algorithm": "Ed25519",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----..."
  },
  "transparency_proof": {
    "log_index": 42,
    "root_hash": "sha256:...",
    "inclusion_proof": ["hash1", "hash2", ...]
  }
}
```

> [!NOTE]
>
> **Cas d'utilisation :** Les bundles de preuves sont idéaux pour les scénarios où les vérificateurs peuvent être
> hors ligne ou souhaitez vérifier indépendamment sans appels API.

## Modèle de vérification

La vérification Truthlocks vérifie plusieurs couches pour déterminer si une attestation doit être approuvée :

**1. Vérification cryptographique**

Vérifiez que la signature Ed25519 correspond à la charge utile en utilisant la clé publique de l'émetteur
clé.

**2. Vérification du statut**

Vérifiez si l'attestation a été révoquée ou remplacée par l'émetteur. Les attestations remplacées renvoient à leur remplacement via `superseded_by_attestation_id`.

**3. Statut de confiance de l'émetteur**

Confirmez que l'émetteur est en statut ACTIF et non suspendu.

**4. Validité de la clé**

Vérifiez que la clé de signature était active au moment de la création de l'attestation.

## Prochaines étapes

> [card] [Environnements](https://docs.truthlocks.com/environments.md)
>
> Découvrez les environnements de développement et de production et leur configuration.

> [card] [Authentification](https://docs.truthlocks.com/security/auth.md)
>
> Approfondissement des clés API, des jetons JWT et de l'intégration OAuth.


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