# API en clientbibliotheken

> Berichten aanmaken, ophalen en verbranden vanuit je eigen code. Regionale basis-URL's, authenticatie, een snelle start met curl, en de officiële en communityclientbibliotheken.

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](https://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.

```plaintext
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](/en/security/where-your-data-lives/) voor wat elke regio voor je gegevens betekent.

Op een [aangepast domein](/nl/custom-domains/) staat de API op hetzelfde pad op je domein, en de links die de API aanmaakt gebruiken dat domein:

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

Een [zelfgehoste](/nl/self-hosting/) 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.

```bash
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](/en/share/your-receipt/).

## Snel aan de slag

Maak een bericht aan dat één uur bestaat:

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

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:

```bash
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:

```bash
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](https://api.onetimesecret.com).

## Clientbibliotheken

[Clientbibliotheken](/nl/api/client-libraries/)De officiële SDK en communitybibliotheken, met notities over welke API v2, regio's en aangepaste domeinen ondersteunen.

[Volledige API-referentie](https://api.onetimesecret.com)Elk 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](/en/security/where-your-data-lives/): een regio kiezen, en wat erbinnen blijft.
* [Aangepaste domeinen](/nl/custom-domains/): berichtlinks en API-toegang op je eigen domein.
* [Zelf hosten](/nl/self-hosting/): draai de API op je eigen infrastructuur.
* [Instap voor ontwikkelaars](/en/contribute/developer-on-ramp/): draai de applicatie lokaal en draag bij.