API et bibliothèques clientes

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

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 pour savoir ce que chaque région implique pour vos données.

Sur un domaine personnalisé, l'API se trouve au même chemin sur votre domaine, et les liens qu'elle crée utilisent ce domaine :

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

Une instance auto-hébergée 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.

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.

Démarrage rapide

Créez un secret qui dure une heure :

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 :

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 :

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.

Bibliothèques clientes

Bibliothèques clientesLe 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'APITous 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 : choisir une région, et ce qui y reste.
Domaines personnalisés : liens secrets et accès API sur votre propre domaine.
Auto-hébergement : exécutez l'API sur votre propre infrastructure.
Parcours d'intégration des développeurs : exécutez l'application en local et contribuez.