API en clientbibliotheken

Alles wat de webapp met een bericht doet, kan via HTTPS met JSON. Het gangbare patroon is een script of pipeline dat een bericht aanmaakt en de link aan een persoon overhandigt, zodat de inloggegevens nooit in een log, een ticket of een chatgeschiedenis terechtkomen.

De volledige endpointreferentie, met request- en responseschema's en een probeer-het-zelf-console, staat op api.onetimesecret.com. Deze pagina behandelt wat je nodig hebt voordat je die opent.

Basis-URL

Verzoeken gaan naar de regio waar je account staat. Elke regio is een aparte deployment en er wordt niets tussen regio's gerepliceerd.

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`

De kale host onetimesecret.com beantwoordt nog steeds API-verzoeken en routeert naar een actieve regio, maar leg een regio expliciet vast zodat je integratie blijft werken als die terugvaloptie wordt uitgefaseerd. Zie Waar je gegevens staan voor wat elke regio voor je gegevens betekent.

Op een aangepast domein staat de API op hetzelfde pad op je domein, en de links die de API aanmaakt gebruiken dat domein:

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

Een zelfgehoste instantie biedt dezelfde API aan op de host waarop je die draait.

Authenticatie

Gebruik HTTP Basic-authenticatie. De gebruikersnaam is het e-mailadres van je account; het wachtwoord is het API-token uit je accountinstellingen.

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

Berichten aanmaken en onthullen werkt ook zonder authenticatie, met de limieten van een anonieme gebruiker: een kortere maximale levensduur, een kleinere berichtgrootte en geen lijst met ontvangstbewijzen. Geauthenticeerde verzoeken krijgen de limieten van je plan en verschijnen in je ontvangstbewijzen.

Snel aan de slag

Maak een bericht aan dat één uur bestaat:

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

De response bevat twee records. record.secret.identifier is de sleutel die je deelt, als https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier is voor jou: die toont of het bericht is bekeken en laat je het vroegtijdig verbranden. Stuur de ontvangstbewijssleutel nooit naar de ontvanger.

Voeg "passphrase": "..." toe aan het object secret om bij het bekijken een wachtwoordzin te vereisen. De wachtwoordzin is een toegangscontrole, niet de versleutelingssleutel: de service slaat alleen een eenrichtingshash ervan op en controleert de wachtwoordzin voordat de waarde wordt ontsleuteld. Een verloren wachtwoordzin kan niet worden hersteld, dus het bericht kan dan niet worden onthuld of verbrand; het wordt verwijderd wanneer het verloopt.

Onthul een bericht, waarmee het wordt verbruikt:

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

Verbrand een bericht voordat iemand het bekijkt, met de ontvangstbewijssleutel:

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

API-versies

v2 is de huidige publieke API: JSON in en uit, ontvangstbewijzen, status- en burn-endpoints. Bouw hierop.
v1 is de oorspronkelijke form-encoded API (POST /api/v1/share). Die werkt nog steeds, en de meeste communitybibliotheken gebruiken die, maar voor nieuwe integraties kun je beter v2 gebruiken.

Beide zijn gedocumenteerd op api.onetimesecret.com.

Clientbibliotheken

ClientbibliothekenDe officiële SDK en communitybibliotheken, met notities over welke API v2, regio's en aangepaste domeinen ondersteunen.

Volledige API-referentieElk endpoint voor v1 en v2, request- en responseschema's, en een console om aanroepen tegen je account uit te proberen.

Gerelateerd

Waar je gegevens staan: een regio kiezen, en wat erbinnen blijft.
Aangepaste domeinen: berichtlinks en API-toegang op je eigen domein.
Zelf hosten: draai de API op je eigen infrastructuur.
Instap voor ontwikkelaars: draai de applicatie lokaal en draag bij.