API und Client-Bibliotheken

Alles, was die Web-App mit einem Geheimnis tut, lässt sich auch über HTTPS mit JSON erledigen. Das übliche Muster ist ein Skript oder eine Pipeline, die ein Geheimnis erstellt und den Link an eine Person weitergibt, sodass die Zugangsdaten nie in einem Log, einem Ticket oder einem Chatverlauf liegen.

Die vollständige Endpunkt-Referenz mit Request- und Response-Schemata und einer Konsole zum Ausprobieren findest du unter api.onetimesecret.com. Diese Seite behandelt, was du wissen musst, bevor du sie öffnest.

Basis-URL

Anfragen gehen an die Region, in der dein Konto liegt. Jede Region ist ein eigenes Deployment, und zwischen den Regionen wird nichts repliziert.

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

`REGION`	Host
`ca`	`ca.onetimesecret.com`
`eu`	`eu.onetimesecret.com`
`nz`	`nz.onetimesecret.com`
`uk`	`uk.onetimesecret.com`
`us`	`us.onetimesecret.com`

Der Host onetimesecret.com ohne Regionspräfix beantwortet API-Anfragen weiterhin und leitet an eine aktive Region weiter. Lege die Region trotzdem ausdrücklich fest, damit deine Integration weiter funktioniert, falls dieser Fallback eingestellt wird. Was jede Region für deine Daten bedeutet, steht unter Wo deine Daten liegen.

Auf einer benutzerdefinierten Domain ist die API unter demselben Pfad auf deiner Domain erreichbar, und die erstellten Links verwenden diese Domain:

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

Eine selbst gehostete Instanz stellt dieselbe API auf dem Host bereit, auf dem du sie betreibst.

Authentifizierung

Verwende HTTP-Basic-Authentifizierung. Der Benutzername ist die E-Mail-Adresse deines Kontos; das Passwort ist das API-Token aus deinen Kontoeinstellungen.

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

Geheimnisse erstellen und aufdecken funktioniert auch ohne Authentifizierung, mit den Grenzen eines anonymen Nutzers: kürzere maximale Lebensdauer, kleinere Geheimnisgröße und keine Belegliste. Authentifizierte Anfragen erhalten die Limits deines Plans und erscheinen in deinen Belegen.

Schnellstart

Erstelle ein Geheimnis, das eine Stunde lang gültig ist:

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

Die Antwort enthält zwei Datensätze. record.secret.identifier ist der Schlüssel, den du teilst, in der Form https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier gehört dir: Er zeigt, ob das Geheimnis angesehen wurde, und erlaubt dir, es vorzeitig zu löschen. Sende den Beleg-Schlüssel niemals an den Empfänger.

Füge dem secret-Objekt "passphrase": "..." hinzu, um beim Ansehen eine Passphrase zu verlangen. Die Passphrase ist eine Zugriffsprüfung, nicht der Verschlüsselungsschlüssel: Der Dienst speichert von ihr nur einen Einweg-Hash und prüft sie, bevor er den Wert entschlüsselt. Die Passphrase lässt sich nicht wiederherstellen. Ein Geheimnis, dessen Passphrase verloren gegangen ist, lässt sich daher weder aufdecken noch löschen und wird erst gelöscht, wenn es abläuft.

Decke ein Geheimnis auf, wodurch es verbraucht wird:

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

Lösche ein Geheimnis mit dem Beleg-Schlüssel, bevor es jemand ansieht:

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

API-Versionen

v2 ist die aktuelle öffentliche API: JSON rein und raus, Belege, Status- und Lösch-Endpunkte. Baue auf dieser Version auf.
v1 ist die ursprüngliche formularkodierte API (POST /api/v1/share). Sie funktioniert weiterhin, und die meisten Community-Bibliotheken verwenden sie, aber neue Integrationen sollten v2 nutzen.

Beide sind unter api.onetimesecret.com dokumentiert.

Client-Bibliotheken

Client-BibliothekenDas offizielle SDK und Community-Bibliotheken, mit Hinweisen dazu, welche API v2, Regionen und benutzerdefinierte Domains unterstützen.

Vollständige API-ReferenzJeder Endpunkt für v1 und v2, Request- und Response-Schemata und eine Konsole, um Aufrufe gegen dein Konto auszuprobieren.