Dokumention - API

Überblick

Die Basis-URL für alle API-Endpunkte ist:

https://password.link/api

Sie können die API verwenden, um sowohl die Verschlüsselung als auch die Entschlüsselung des Geheimnisses außerhalb unseres Dienstes zu handhaben, ohne dass Sie irgendwelche Assets von uns laden müssen. Außerdem können Sie jede beliebige Übermittlungsmethode für den Teil des öffentlichen Kennworts (die Hälfte des Kennworts, aus dem der Verschlüsselungsschlüssel für das Geheimnis abgeleitet wird) verwenden und grundsätzlich jede beliebige benutzerdefinierte Konfiguration für die Anzeige des Geheimnisses erstellen.

Funktionierenden End-to-End-Code finden Sie in den API-Beispiele.

Authentifizierung

Jede Anfrage muss mit einem API-Schlüssel authentifiziert werden, der im Authorization-Header gesendet wird:

Authorization: ApiKey public_key_abcd...

Es gibt zwei Arten von API-Schlüsseln:

Beide API-Schlüssel enthalten den Typ des Schlüssels im Schlüssel selbst, so dass sie leicht unterschieden werden können.

Bei jedem Endpunkt unten ist angegeben, welchen Schlüsseltyp er erfordert.

Fehler

Wenn eine Anfrage fehlschlägt, enthält die Antwort ein Fehlerobjekt:

{
  "data": null,
  "metadata": null,
  "error": {
    "message": "Ciphertext can't be blank",
    "field": "ciphertext"
  }
}

Der HTTP-Statuscode der Antwort gibt ebenfalls die Art des Fehlers an:

Geheimnisse verschlüsseln

Geheimnisse werden clientseitig verschlüsselt, bevor sie an die API gesendet werden. Dieser Abschnitt beschreibt die Passwort- und Ciphertext-Formate, die der Dienst erwartet.

Die Passwortteile

Das Passwort, das zur Verschlüsselung des Geheimnisses in AES verwendet wird, muss aus zwei 18 Zeichen langen Zeichenketten bestehen. Der eigentliche Verschlüsselungsschlüssel ist die Verkettung dieser beiden Zeichenfolgen ("privater Teil" + "öffentlicher Teil") und wird unter Verwendung von PBKDF2 aus dem Passwort abgeleitet.

Password: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
  => Private part: fkgjbnvlakwiejgutn
  => Public part:  FIGKEOTIRUBNAKQJRL

Der private Teil wird (Base64-kodiert) an die API gesendet und mit dem Geheimnis gespeichert. Der öffentliche Teil wird niemals an die API gesendet und in der Regel im Link selbst übermittelt, sodass wir das Geheimnis niemals selbst entschlüsseln können.

Wenn Sie die von uns bereitgestellte Seite zum Anzeigen des Geheimnisses verwenden, müssen Sie auch den öffentlichen Teil Base64-kodieren. Wenn Sie eine selbst gehostete Anzeigeseite verwenden, können Sie dieselbe Methode verwenden oder eine eigene erstellen. Referenzimplementierungen finden Sie in den API-Beispiele.

Chiffretext-Format

Der Chiffretext ist ein JSON-Objekt, Base64-codiert:

{
  "cipher": "<Base64 encoded AES-GCM ciphertext>",
  "iv": "<Base64 encoded 12-byte initialization vector>",
  "salt": "<Base64 encoded 16-byte PBKDF2 salt>",
  "iter": 10000
}

Für die Verschlüsselung des Geheimnisses müssen Sie die folgenden Einstellungen für AES verwenden:

Älteres SJCL-Format (veraltet)

Geheimnisse entschlüsseln

Die API „Ansicht Geheimnis“ gibt den Ciphertext genau so zurück, wie er gespeichert wurde. In der Web-App erstellte Geheimnisse verwenden das oben beschriebene Web-Crypto-Format. Geheimnisse, die von älteren API-Clients, der Chrome-Erweiterung oder über noch nicht geöffnete Links erstellt wurden, können das ältere SJCL-Format verwenden.

Eine selbst gehostete Anzeigeseite muss beide Formate verarbeiten. Dekodieren Sie den Ciphertext von Base64 zu JSON und prüfen Sie dann auf einen ct-Schlüssel: Ist er vorhanden, entschlüsseln Sie mit SJCL, andernfalls mit Web Crypto. Siehe das Beispiel „Ansicht Geheimnis“.

Geheimnis erstellen

Erstellt ein verschlüsseltes Geheimnis und gibt dessen ID zurück. Der Ciphertext muss wie in Geheimnisse verschlüsseln beschrieben erstellt werden. Gibt bei Erfolg 201 Created zurück.

Parameter anfordern

Beispielanfrage

curl -H "Authorization: ApiKey private_key_abcd" \
     -H "Content-Type: application/json" \
     -X POST https://password.link/api/secrets \
     -d '{
       "ciphertext": "eyJjaXBoZXIiOiJRc3hxsN3...aXRlciI6MTAwMDB9",
       "password_part_private": "ZmtnamJudmxha3dpZWpndXRu",
       "description": "Database credentials",
       "expiration": 24,
       "view_button": true,
       "max_views": 1
     }'

Beispielantwort

{
  "data": {
    "id": "dT5g"
  },
  "metadata": {
    "secrets_total": 70,
    "secrets_usage": 25,
    "secrets_allowance": 100,
    "secret_requests_total": 10,
    "secret_requests_allowance": 100
  }
}

Der Link zum Geheimnis wird gebildet, indem die URL der gehosteten Anzeigeseite, die ID des Geheimnisses und der Base64-kodierte öffentliche Passwortteil kombiniert werden:

https://password.link/<id>/#<public password part, Base64>

Anhänge

Das Hochladen eines Anhangs erfolgt in zwei Schritten: Erstellen Sie zuerst das Geheimnis mit den Anhang-Metadaten (siehe Geheimnis erstellen), verschlüsseln Sie dann die Anhangsdaten und laden Sie sie zur zurückgegebenen Upload-URL hoch.

Der Inhalt des Geheimnisses und der Inhalt des Anhangs werden separat verschlüsselt. Beide verwenden Web-Crypto-kompatible AES-GCM-Daten, Base64-codiert, aber die Felder der Nutzlast sind unterschiedlich codiert: Die Nutzlast des Geheimnisses enthält Base64-codierte Felder und ein iter-Feld, während die Nutzlast des Anhangs Felder mit rohen Binärzeichenketten enthält.

Verschlüsseln des Anhangs

Stellen Sie die Datei vor der Verschlüsselung als Daten-URL dar:

data:<mime-type>;base64,<base64 file bytes>

Das Verschlüsselungspasswort des Anhangs ist der rohe private Passwortteil, verkettet mit dem rohen öffentlichen Passwortteil (ohne Base64-Kodierung).

Verschlüsseln Sie diesen Data-URL-String mit AES-GCM unter Verwendung von PBKDF2-SHA256, 10000 Iterationen, einem abgeleiteten 256-Bit-Schlüssel, einem zufälligen 16-Byte-Salt und einem zufälligen 12-Byte-IV. Speichern Sie die verschlüsselten Anhangsdaten als JSON-Objekt und kodieren Sie den JSON-String dann in Base64:

{
  "cipher": "<binary string>",
  "iv": "<binary string>",
  "salt": "<binary string>"
}

Hochladen der verschlüsselten Datei

Wenn ein Anhang enthalten ist, enthält die Antwort auf die Geheimnis-Erstellung ein Upload-Ziel in data.attachment.upload:

{
  "data": {
    "id": "dT5g",
    "attachment": {
      "file_name": "example.txt",
      "upload": {
        "url": "/api/secrets/dT5g/attachment",
        "fields": {},
        "metadata": {}
      }
    }
  },
  "metadata": {}
}

Laden Sie das Base64-kodierte verschlüsselte JSON als text/plain über multipart/form-data zur zurückgegebenen upload.url hoch. Fügen Sie alle zurückgegebenen upload.metadata- oder upload.fields-Schlüssel/Wert-Paare den Formulardaten hinzu, bevor Sie die verschlüsselte Datei hinzufügen. Das Feld der verschlüsselten Datei muss file heißen.

Fügen Sie bei Password.link-Upload-URLs denselben privaten API-Schlüssel im Header Authorization: ApiKey <key> hinzu. Direkte Speicher-Upload-URLs, wie vorab signierte S3-URLs, sollten nur die zurückgegebenen Formularfelder und das verschlüsselte Feld file erhalten.

Ansicht Geheimnis

Ruft den Ciphertext, den privaten Passwortteil und andere Details eines Geheimnisses ab. Dieser Endpunkt kann verwendet werden, um eine eigene, selbst gehostete Seite zum Anzeigen von Geheimnissen zu erstellen, die keine Skripte oder andere Ressourcen von unserem Dienst lädt. Gibt bei Erfolg 200 OK zurück.

Wenn das Geheimnis mit einem OTP-Code oder einem Passwort geschützt ist, senden Sie diesen in einem Request-Header. Werte im Query-String werden nicht akzeptiert. Ohne gültigen Wert wird 403 Forbidden zurückgegeben, wobei secret_status auf otp_required oder password_required gesetzt ist. Wenn ein Geheimnis sowohl einen OTP-Empfänger als auch ein Passwort hat, wird nur der OTP-Code geprüft, genau wie beim Öffnen des Geheimnisses im Browser.

Der OTP-Code wird an den OTP-Empfänger gesendet, wenn dieser den Link zum Geheimnis öffnet. Die API versendet ihn nicht. Geheimnisse, die lediglich die zulässigen Empfänger-E-Mail-Adressen einschränken, erfordern über die API keinen OTP-Code.

Request-Header

Beispielanfrage

curl -H "Authorization: ApiKey public_key_abcd" \
     https://password.link/api/secrets/dT5g

Beispielantwort

{
  "data": {
    "id": "dT5g",
    "ciphertext": "eyJjaXBoZXIiOiJRc3hxsN3...aXRlciI6MTAwMDB9",
    "password_part_private": "ZmtnamJudmxha3dpZWpndXRu",
    "message": "Here are the credentials we talked about"
  },
  "metadata": null
}

Secret bestätigen

Übermittelt die Empfängerbestätigung für ein Geheimnis, das mit ack_required erstellt wurde, und gibt dieselben Geheimnis-Daten wie View Secret zurück, wenn die Bestätigung gültig ist. Gibt bei Erfolg 200 OK zurück.

Wenn eine Bestätigung erforderlich ist, gibt GET /api/secrets/<id> 403 Forbidden zurück, wobei secret_status auf ack_required gesetzt ist, bis dieser Endpunkt verwendet wird.

Ungültige oder unvollständige Bestätigungsdaten geben ebenfalls 403 Forbidden zurück. Sie werden nicht als Validierungsfehler zurückgegeben.

Wenn das Geheimnis mit einem OTP-Code oder einem Passwort geschützt ist, senden Sie diesen in denselben Headern wie bei „Ansicht Geheimnis“ oder als otp und password im JSON-Request-Body.

Parameter anfordern

Beispielanfrage

curl -H "Authorization: ApiKey public_key_abcd" \
     -H "Content-Type: application/json" \
     -X POST https://password.link/api/secrets/dT5g/acknowledge \
     -d '{"ack_confirmed": true, "ack_signer_name": "Jane Doe"}'

Liste Geheimnisse

Ruft eine Liste von Geheimnissen ab. Enthält keine Ciphertexte oder private Passwortteile, nur IDs, Beschreibungen und Ähnliches. Gibt bei Erfolg 200 OK zurück.

Die maximale Anzahl zurückgegebener Ergebnisse pro Abfrage ist auf 50 begrenzt. Sie können den Offset mit dem optionalen Abfrageparameter offset steuern, zum Beispiel: /api/secrets?offset=50

Beispielanfrage

curl -H "Authorization: ApiKey private_key_abcd" \
     https://password.link/api/secrets

Beispielantwort

{
  "data": [
    {
      "id": "dT5g",
      "created_at": "2026-07-02T10:00:00.000Z",
      "message": "Here are the credentials we talked about",
      "description": "Database credentials",
      "view_button": true,
      "captcha": false,
      "password": false,
      "expiration": 24,
      "expired": false,
      "view_times": 1,
      "max_views": 1,
      "secret_folder_id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
      "views": [
        {
          "viewed_at": "2026-07-02T12:34:56.000Z",
          "viewed_by_ip": "192.0.2.10",
          "viewed_by_user_agent": "Mozilla/5.0 ..."
        }
      ]
    }
  ],
  "metadata": {
    "secrets_total": 70,
    "secrets_usage": 25,
    "secrets_allowance": 100,
    "secret_requests_total": 10,
    "secret_requests_allowance": 100
  }
}

Secret aktualisieren

Aktualisiert unterstützte Einstellungen und Metadaten eines vorhandenen Geheimnisses. Gibt bei Erfolg 204 No Content zurück.

PATCH ersetzt nicht den verschlüsselten Inhalt des Geheimnisses, versendet keine Zustellungs-E-Mails erneut und erstellt keine Anhang-Upload-Metadaten. Verwenden Sie Create Secret für Ciphertext, Passwortteile, Link-Zustellung und Anhänge.

Die folgenden Parameter können aktualisiert werden, mit derselben Bedeutung wie in Create Secret:

description, message, expiration, max_views, view_button, captcha, password, otp_email_recipient, otp_recipient, otp_sms_recipient, allowed_ips, allowed_locations, available_after, secret_folder_id, reply_enabled, ack_required, ack_mode, ack_phrase, ack_disclosure_text, ack_collect_name, ack_name_required, ack_collect_org

Beispielanfrage

curl -H "Authorization: ApiKey private_key_abcd" \
     -H "Content-Type: application/json" \
     -X PATCH https://password.link/api/secrets/dT5g \
     -d '{"description": "Updated description", "otp_email_recipient": "recipient@example.com"}'

Geheimnis löschen

Löscht ein Geheimnis. Gibt bei Erfolg 200 OK zurück.

Beispielanfrage

curl -H "Authorization: ApiKey private_key_abcd" \
     -X DELETE https://password.link/api/secrets/dT5g

Beispielantwort

{
  "data": null,
  "metadata": {
    "secrets_total": 69,
    "secrets_usage": 24,
    "secrets_allowance": 100,
    "secret_requests_total": 10,
    "secret_requests_allowance": 100
  }
}

Secret-Ordner erstellen

Erstellt einen Geheimnis-Ordner. Gibt bei Erfolg 201 Created zurück.

Parameter anfordern

Beispielantwort

{
  "data": {
    "id": "5e976e6e-d205-4f58-8df9-5ac0048bc702"
  },
  "metadata": {
    "secrets_total": 70,
    "secrets_usage": 25,
    "secrets_allowance": 100,
    "secret_requests_total": 10,
    "secret_requests_allowance": 100
  }
}

Secret-Ordner auflisten

Ruft eine Liste von Geheimnis-Ordnern ab. Gibt bei Erfolg 200 OK zurück.

Beispielantwort

{
  "data": [
    {
      "id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
      "name": "Clients",
      "description": "Client credentials",
      "created_at": "2026-07-02T10:00:00.000Z",
      "updated_at": "2026-07-02T10:00:00.000Z"
    }
  ],
  "metadata": {
    "secrets_total": 70,
    "secrets_usage": 25,
    "secrets_allowance": 100,
    "secret_requests_total": 10,
    "secret_requests_allowance": 100
  }
}

Secret-Ordner aktualisieren

Aktualisiert den Namen und die Beschreibung eines Geheimnis-Ordners. Akzeptiert dieselben Parameter wie Create Secret Folder und gibt bei Erfolg 204 No Content zurück.

Geheimordner löschen

Löscht einen Geheimnis-Ordner. Gibt bei Erfolg 200 OK zurück.

Geheime Anfrage erstellen

Erstellt eine neue geheime Anfrage. Gibt bei Erfolg 201 Created zurück.

Parameter anfordern

Beispielanfrage

curl -H "Authorization: ApiKey private_key_abcd" \
     -H "Content-Type: application/json" \
     -X POST https://password.link/api/secret_requests \
     -d '{"description": "Request for VPN credentials", "expiration": 48}'

Beispielantwort

{
  "data": {
    "id": "5e976e6e-d205-4f58-8df9-5ac0048bc702"
  },
  "metadata": {
    "secrets_total": 70,
    "secrets_usage": 25,
    "secrets_allowance": 100,
    "secret_requests_total": 10,
    "secret_requests_allowance": 100
  }
}

Liste der geheimen Ersuchen

Ruft eine Liste geheimer Anfragen ab. Gibt bei Erfolg 200 OK zurück.

Die maximale Anzahl zurückgegebener Ergebnisse pro Abfrage ist auf 50 begrenzt. Sie können den Offset mit dem optionalen Abfrageparameter offset steuern, zum Beispiel: /api/secret_requests?offset=50

Die Listenantwort enthält weder secret_allowed_emails noch secret_allowed_ips.

Beispielanfrage

curl -H "Authorization: ApiKey private_key_abcd" \
     https://password.link/api/secret_requests

Beispielantwort

{
  "data": [
    {
      "id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
      "description": "Request for VPN credentials",
      "message": "Please send me the VPN credentials",
      "expiration": 48,
      "limit": 1,
      "send_request_to_email": "request-recipient@example.com",
      "send_request_to_sms": "+358401234567",
      "send_to_email": "example@example.com",
      "secret_description": "VPN credentials",
      "secret_message": null,
      "secret_expiration": 24,
      "secret_max_views": 1,
      "secret_password": false,
      "template_id": null
    }
  ],
  "metadata": {
    "secrets_total": 70,
    "secrets_usage": 25,
    "secrets_allowance": 100,
    "secret_requests_total": 10,
    "secret_requests_allowance": 100
  }
}

Geheime Anfrage löschen

Löscht eine geheime Anfrage. Gibt bei Erfolg 200 OK zurück.

Beispielanfrage

curl -H "Authorization: ApiKey private_key_abcd" \
     -X DELETE https://password.link/api/secret_requests/5e976e6e-d205-4f58-8df9-5ac0048bc702