# API et bibliothèques clientes

> Créez, récupérez et brûlez des secrets depuis votre propre code. URL de base régionales, authentification, démarrage rapide avec curl, et bibliothèques clientes officielles et communautaires.

Tout ce que l'application web fait avec un secret peut être fait en HTTPS avec du JSON. Le schéma le plus courant est un script ou un pipeline qui crée un secret et transmet le lien à une personne, de sorte que les identifiants ne restent jamais dans un journal, un ticket ou un historique de conversation.

La référence complète des points de terminaison, avec les schémas de requête et de réponse et une console d'essai, se trouve sur **[api.onetimesecret.com](https://api.onetimesecret.com)**. Cette page couvre ce dont vous avez besoin avant de l'ouvrir.

## URL de base

Les requêtes sont envoyées à la région qui héberge votre compte. Chaque région est un déploiement distinct et rien n'est répliqué entre elles.

```plaintext
https://REGION.onetimesecret.com/api/v2
```

| `REGION` | Hôte           |
| -------- | ---------------------- |
| `ca`     | `ca.onetimesecret.com` |
| `eu`     | `eu.onetimesecret.com` |
| `nz`     | `nz.onetimesecret.com` |
| `uk`     | `uk.onetimesecret.com` |
| `us`     | `us.onetimesecret.com` |

L'hôte nu `onetimesecret.com` répond toujours aux requêtes API et les route vers une région active, mais indiquez explicitement une région afin que votre intégration continue de fonctionner si ce mécanisme de repli est retiré. Consultez [Où résident vos données](/en/security/where-your-data-lives/) pour savoir ce que chaque région implique pour vos données.

Sur un [domaine personnalisé](/fr/custom-domains/), l'API se trouve au même chemin sur votre domaine, et les liens qu'elle crée utilisent ce domaine :

```plaintext
https://secrets.example.com/api/v2
```

Une instance [auto-hébergée](/fr/self-hosting/) expose la même API sur l'hôte sur lequel vous l'exécutez.

## Authentification

Utilisez l'authentification HTTP Basic. Le nom d'utilisateur est l'adresse e-mail de votre compte ; le mot de passe est le jeton API disponible dans les paramètres de votre compte.

```bash
curl -u 'you@example.com:APITOKEN' https://eu.onetimesecret.com/api/v2/status
```

La création et la révélation de secrets fonctionnent aussi sans authentification, avec les limites d'un utilisateur anonyme : durée de vie maximale plus courte, taille de secret plus petite et aucune liste de reçus. Les requêtes authentifiées bénéficient des limites de votre forfait et apparaissent dans vos [reçus](/en/share/your-receipt/).

## Démarrage rapide

Créez un secret qui dure une heure :

```bash
curl -u 'you@example.com:APITOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"secret": {"secret": "the password is hunter2", "ttl": 3600}}' \
  https://eu.onetimesecret.com/api/v2/secret/conceal
```

La réponse contient deux enregistrements. `record.secret.identifier` est la clé que vous partagez, sous la forme `https://eu.onetimesecret.com/secret/IDENTIFIER`. `record.receipt.identifier` est la vôtre : elle indique si le secret a été consulté et vous permet de le brûler avant terme. N'envoyez jamais la clé du reçu au destinataire.

Ajoutez `"passphrase": "..."` à l'objet `secret` pour exiger une phrase secrète lors de la consultation. La phrase secrète sert de contrôle d'accès et non de clé de chiffrement : le service n'en stocke qu'un hachage à sens unique et la vérifie avant de déchiffrer la valeur. Une phrase secrète perdue ne peut pas être récupérée, si bien que le secret ne peut alors être ni révélé ni brûlé ; il est supprimé à son expiration.

Révélez un secret, ce qui le consomme :

```bash
curl -X POST -H 'Content-Type: application/json' -d '{}' \
  https://eu.onetimesecret.com/api/v2/secret/IDENTIFIER/reveal
```

Brûlez un secret avant que quiconque le consulte, à l'aide de la clé du reçu :

```bash
curl -u 'you@example.com:APITOKEN' -X POST \
  https://eu.onetimesecret.com/api/v2/receipt/RECEIPT_IDENTIFIER/burn
```

## Versions de l'API

* **v2** est l'API publique actuelle : JSON en entrée et en sortie, reçus, points de terminaison de statut et de brûlage. C'est celle-ci qu'il faut utiliser.
* **v1** est l'API d'origine encodée en formulaire (`POST /api/v1/share`). Elle fonctionne toujours, et la plupart des bibliothèques communautaires l'utilisent, mais les nouvelles intégrations doivent utiliser la v2.

Les deux sont documentées sur [api.onetimesecret.com](https://api.onetimesecret.com).

## Bibliothèques clientes

[Bibliothèques clientes](/fr/api/client-libraries/)Le SDK officiel et les bibliothèques communautaires, avec des notes sur celles qui prennent en charge l'API v2, les régions et les domaines personnalisés.

[Référence complète de l'API](https://api.onetimesecret.com)Tous les points de terminaison des v1 et v2, les schémas de requête et de réponse, et une console pour tester des appels sur votre compte.

## Voir aussi

* [Où résident vos données](/en/security/where-your-data-lives/) : choisir une région, et ce qui y reste.
* [Domaines personnalisés](/fr/custom-domains/) : liens secrets et accès API sur votre propre domaine.
* [Auto-hébergement](/fr/self-hosting/) : exécutez l'API sur votre propre infrastructure.
* [Parcours d'intégration des développeurs](/en/contribute/developer-on-ramp/) : exécutez l'application en local et contribuez.