# API und Client-Bibliotheken

> Geheimnisse aus deinem eigenen Code erstellen, abrufen und löschen: regionale Basis-URLs, Authentifizierung, ein curl-Schnellstart sowie die offiziellen und Community-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](https://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.

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

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](/en/security/where-your-data-lives/).

Auf einer [benutzerdefinierten Domain](/de/custom-domains/) ist die API unter demselben Pfad auf deiner Domain erreichbar, und die erstellten Links verwenden diese Domain:

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

Eine [selbst gehostete](/de/self-hosting/) 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.

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

## Schnellstart

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

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

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:

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

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

## Client-Bibliotheken

[Client-Bibliotheken](/de/api/client-libraries/)Das offizielle SDK und Community-Bibliotheken, mit Hinweisen dazu, welche API v2, Regionen und benutzerdefinierte Domains unterstützen.

[Vollständige API-Referenz](https://api.onetimesecret.com)Jeder Endpunkt für v1 und v2, Request- und Response-Schemata und eine Konsole, um Aufrufe gegen dein Konto auszuprobieren.

## Verwandte Themen

* [Wo deine Daten liegen](/en/security/where-your-data-lives/): eine Region wählen und was innerhalb der Region bleibt.
* [Benutzerdefinierte Domains](/de/custom-domains/): geheime Links und API-Zugriff auf deiner eigenen Domain.
* [Self-Hosting](/de/self-hosting/): die API auf deiner eigenen Infrastruktur betreiben.
* [Einstieg für Entwickler](/en/contribute/developer-on-ramp/): die Anwendung lokal ausführen und mitwirken.