API-dokumentation

Allmänt

Vi har ett standard REST API för att hantera hemligheter. Alla förfrågningar och svar använder JSON format.

Du kan använda API:et för att hantera både kryptering och dekryptering av hemligheten utanför vår tjänst, utan att behöva ladda några tillgångar från oss. Det tillåter också dig att använda vilken typ av leveransmetod som helst för den publika lösenordsdelen (halva lösenordet som används för att härleda krypteringsnyckeln för hemligheten från) och i princip skapa vilken typ av anpassad konfiguration som helst för att visa hemligheten.

Kodexempel

Vänligen se våra API-exempel om hur man använder API:et.

Autentisering

Vi använder två typer av API-nycklar för autentisering:

• Publika API-nycklar
• Privata API-nycklar

Publika API-nycklar är avsedda för att skapa en anpassad själv-hostad sida för visning av hemlighet. Alla andra API-åtgärder kräver en privat API-nyckel.

Publika API-nycklar kan användas i offentliga skript. Privata API-nycklar måste alltid hållas privata.

Båda API-nycklarna innehåller typ av nyckel i själva nyckeln så att de lätt kan särskiljas.

API-nyckeln måste skickas i Authorization: ApiKey <key> header, såsom:

Authorization: ApiKey public_key_abc...

Fel

Vid misslyckad förfrågan kommer svaret att ha ett error objekt.

Objektet innehåller följande fält:

• message: det fullständiga felmeddelandet, t.ex. "Ciphertext kan inte vara tom"
• field: fältet som felet gäller, t.ex. "ciphertext"

HTTP-svarsstatuskoden kommer också att indikera ett fel, till exempel:

• 403 Förbjudet: förfrågan tilläts inte, till exempel på grund av ogiltig API-nyckel
• 404 Hittades inte: den begärda hemligheten hittades inte

Visa hemlighet

Förfrågningstyp: GET

Förfrågningssökväg: https://password.link/api/secrets/<id>

Statuskod för lyckad förfrågan: 200 OK

Hämta chiffertexten, privata lösenordsdelen och andra detaljer om en hemlighet. Kräver publik API-nyckel.

Denna API-förfrågan kan användas för att skapa en anpassad själv-hostad sida för visning av hemlighet som inte laddar några skript eller andra tillgångar från vår tjänst.

Att framgångsrikt hämta en hemlighet markerar den automatiskt som visad och raderar därmed chiffertexten och den privata lösenordsdelen från vår databas, vilket gör det omöjligt att visa hemligheten igen.

Obligatoriska parametrar

• id: id för hemligheten, till exempel dT5g

Exempel på fråga

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

Exempel på svar

{
        "data": {
          "id": "iD för den hemliga informationen",
          "ciphertext": "chiffertexten för hemligheten",
          "password_part_private": "den privata lösenordsdelen av hemligheten",
          "message": "meddelandet för hemligheten, om angivet"
        },
        "metadata": null
      }

Kodexempel

Vänligen se våra API-exempel.

Skapa hemlighet

Förfrågningstyp: POST

Förfrågningssökväg: https://password.link/api/secrets

Statuskod för lyckad förfrågan: 201 Created

Detta API-anrop stöder också att lägga till en krypterad filbilaga till hemligheten.

Skapa en krypterad hemlighet.

Att kryptera hemligheten på klientsidan innan den skickas till vårt API kräver att en SJCL-kompatibel chiffertext JSON-sträng skapas. Vänligen se <a href=\"https://github.com/bitwiseshiftleft/sjcl\">SJCL-dokumentation</a> för korrekt format av JSON-strängen, och se våra <a href=\"/p/docs/api/examples\">Exempel på API</a> för exempel på hur man skapar chiffertexten.

Skapa lösenordet för att kryptera hemligheten

Lösenordet som används för att kryptera hemligheten i AES måste bestå av två 18 tecken långa strängar. Den faktiska krypteringsnyckeln kommer att vara sammanfogningen av dessa två strängar ("privat del" + "publik del") och härleds från lösenordet av SJCL med PBKDF2.

Exempel på att skapa de privata och publika lösenordsdelarna:

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

Den privata delen måste vara Base64-kodad innan den skickas till vårt API. Om du använder sidan för visning av hemlighet som tillhandahålls av oss måste du också Base64-koda den publika delen. Om du använder en själv-hostad sida för visning av hemlighet kan du använda samma metod eller skapa din egen. Vänligen se våra <a href=\"/p/docs/api/examples\">Exempel på API</a> för referensimplementationer.

Obligatoriska SJCL AES-inställningar

Du måste använda följande inställningar för AES när du krypterar hemligheten:

• Läge: AES-GCM (SJCL-inställning: "mode:gcm")
• Nyckelstorlek: 256 bits (SJCL-inställning: "ks:256")
• Nyckel härledningsfunktion: PBKDF2 (SJCL standard)
• PBKDF2-iterationer: 10000 (SJCL-inställning: "iter:10000")

Förfrågningsdata

{
        "ciphertext": "ciphertext",
        "password_part_private": "password_part_private",
        "password_part_public": "password_part_public",
        "description": "description",
        "message": "message",
        "expiration": "expiration",
        "view_button": "view_button",
        "captcha": "captcha",
        "password": "password",
        "max_views": "max_views",
        "email_to": "recipient@example.com",
        "otp_email_recipient": "recipient@example.com",
        "otp_sms_recipient": "+358401234567",
        "allowed_ips": "192.0.2.10,198.51.100.0/24",
        "allowed_locations": ["FI", "SE"],
        "available_after": "2026-07-02T12:00:00Z",
        "secret_folder_id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
        "reply_enabled": true,
        "ack_required": true,
        "ack_mode": "ack_mode",
        "ack_phrase": "ack_phrase",
        "ack_disclosure_text": "ack_disclosure_text",
        "ack_collect_name": true,
        "ack_name_required": true,
        "ack_collect_org": true,
        "attachment": {
          "file_name": "file_name",
          "file_type": "file_type",
          "file_size": "file_size"
        }
      }

Parametrar för begäran

• ciphertext: En SJCL-kompatibel chiffertext JSON-sträng av hemligheten, kodad i Base64.
• password_part_private: den privata lösenordsdelen som användes för att kryptera hemligheten, i Base64.
• password_part_public (valfri): den publika lösenordsdelen, i Base64. Krävs endast när du använder email_to så att API:t kan skicka den hostade Secret-länken via e-post.
• description (valfri): en beskrivning för hemligheten. Kan inte ses när hemligheten visas.
• message (valfri): ett meddelande för hemligheten. Visas tillsammans med hemligheten.
• expiration (valfri): en utgångstid för hemligheten, i timmar. Möjliga värden: 1-500.
• view_button (valfri): visa en knapp för att visa hemlighet istället för att visa hemligheten omedelbart efter att länken öppnats. För att aktivera denna funktion, ställ in detta till true.
• captcha (valfri): visa en enkel CAPTCHA innan hemligheten visas, huvudsakligen för att blockera automatiserade skannrar. För att aktivera denna funktion, ställ in detta till true.
• password (valfri): ett lösenord för hemligheten.
• max_views (valfri): hur många gånger hemligheten kan ses. Möjliga värden: 1-100.
• email_to (valfri): kommaavgränsade e-postmottagare som ska få den skapade Secret-länken. Kräver password_part_public.
• otp_email_recipient (valfri): e-postadress som får ett engångslösenord. När den är angiven måste mottagaren ange koden som skickats via e-post innan Secret kan visas.
• otp_recipient (valfri): accepteras som alias för otp_email_recipient. Föredra otp_email_recipient för nya integrationer.
• otp_sms_recipient (valfri): telefonnummer som får ett engångslösenord via SMS, i internationellt format som börjar med + och utan mellanslag.
• allowed_ips (valfri): kommaavgränsade IP-adresser eller CIDR-intervall som får visa Secret.
• allowed_locations (valfri): array med ISO 3166-1 alfa-2-landskoder som får visa Secret.
• available_after (valfri): datum och tid innan vilka Secret inte kan visas.
• secret_folder_id (valfri): ID för en befintlig Secret-mapp som ägs av API-nyckelanvändaren.
• reply_enabled (valfri): aktivera ett engångssvar från mottagaren efter att Secret har visats.
• ack_required (valfri): kräv mottagarbekräftelse innan Secret kan visas.
• ack_mode (valfri): bekräftelseläge. Använd checkbox eller phrase.
• ack_phrase (krävs när ack_required är sant och ack_mode är phrase): frasen som mottagaren måste skriva.
• ack_disclosure_text (valfri): upplysningstext som visas för mottagaren, upp till 500 tecken.
• ack_collect_name (valfri): samla in mottagarens namn med bekräftelsen.
• ack_name_required (valfri): kräv mottagarens namn. Detta aktiverar också ack_collect_name.
• ack_collect_org (valfri): samla in mottagarens organisation med bekräftelsen.
• attachment (valfri): metadata för en krypterad filbilaga. Kräver en aktiv plan. Den krypterade filen laddas upp separat efter att hemligheten har skapats.
• attachment.file_name (krävs när bilaga anges): det ursprungliga filnamnet som visas för mottagaren.
• attachment.file_type (krävs när bilaga anges): den ursprungliga MIME-typen, till exempel text/plain eller application/pdf.
• attachment.file_size (krävs när bilaga anges): den ursprungliga okrypterade filstorleken i byte.

Team Secret Settings kan inaktivera, kräva eller tvinga standardvärden för stödda Secret-alternativ. API:t tillämpar dessa teamregler när ett Secret skapas.

Ladda upp en bilaga

Att ladda upp en bilaga är en tvåstegsprocess: skapa först hemligheten med bilagans metadata, kryptera sedan och ladda upp den krypterade bilagelasten till den returnerade uppladdnings-URL:en.

Hemlighetens innehåll och bilagans innehåll krypteras separat. Hemlighetens chiffertext är SJCL-kompatibla AES-GCM-data, Base64-kodade. Bilagan krypteras med Web Crypto-kompatibla AES-GCM-data och Base64-kodas sedan.

Krypteringslösenordet för bilagan är den råa privata lösenordsdelen sammanfogad med den råa publika lösenordsdelen: <raw private password part> + <raw public password part>.

När en bilaga inkluderas innehåller svaret från skapandet av hemligheten ett uppladdningsmål i data.attachment.upload:

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

Uppladdnings-URL:er som hostas på Password.link inkluderar ett tomt fields-objekt. Direkta lagringsuppladdnings-URL:er, såsom förhandsignerade S3-URL:er, returnerar signeringsfält i metadata istället.

Före kryptering representerar du filen som en data-URL: data:<mime-type>;base64,<base64 file bytes>.

Kryptera den data-URL-strängen med AES-GCM med PBKDF2-SHA256, 10000 iterationer, en härledd 256-bitarsnyckel, ett slumpmässigt 16-byte salt och en slumpmässig 12-byte IV. Lagra den krypterade bilagans payload som ett JSON-objekt som innehåller cipher, iv och salt, och Base64-koda sedan JSON-strängen.

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

Ladda upp den Base64-kodade krypterade JSON:en som text/plain med multipart/form-data till den returnerade upload.url. Lägg till alla returnerade upload.metadata eller upload.fields nyckel/värde-par i formulärdata innan du lägger till den krypterade filen. Fältet för den krypterade filen måste heta file.

För Password.link-uppladdnings-URL:er, inkludera samma privata API-nyckel i Authorization: ApiKey <key>-huvudet. Direkta uppladdnings-URL:er för lagring, till exempel försignerade S3-URL:er, ska endast ta emot de returnerade formulärfälten och det krypterade file-fältet.

API-svaret för att skapa hemlighet returnerar ett uppladdningsmål för bilagan för den enskilda attachment parametern. Storleksgränser för bilagor beror på konto- eller teamtilldelningen, och den krypterade uppladdningen är större än originalfilen eftersom filen konverteras till Base64 och krypteras.

Kodexempel

Vänligen se våra API-exempel.

Bekräfta Secret

Förfrågningstyp: POST

Förfrågningssökväg: https://password.link/api/secrets/<id>/acknowledge

Statuskod för lyckad förfrågan: 200 OK

Skicka mottagarbekräftelse för ett Secret som skapades med ack_required. Kräver den publik API-nyckeln och returnerar samma Secret-data som Visa Secret när bekräftelsen är giltig.

Om bekräftelse krävs, GET /api/secrets/<id> returnerar 403 Forbidden med secret_status satt till ack_required tills denna endpoint används.

Ogiltiga eller ofullständiga bekräftelsepayloads returnerar också 403 Forbidden. De returneras inte som valideringsfel.

Parametrar för begäran

• ack_confirmed: satt till true för kryssrutebekräftelse.
• ack_phrase: krävs för frasbekräftelse och måste matcha frasen som konfigurerats för Secret.
• ack_signer_name: mottagarens namn, krävs när namninsamling är aktiverad och markerad som obligatorisk.
• ack_signer_org: mottagarens organisation, lagras när organisationsinsamling är aktiverad.

Exempel på fråga

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"}'

Exempel på svar

{
        "data": {
          "id": "iD för den hemliga informationen",
          "ciphertext": "chiffertexten för hemligheten",
          "password_part_private": "den privata lösenordsdelen av hemligheten",
          "message": "meddelandet för hemligheten, om angivet"
        },
        "metadata": null
      }

Lista hemligheter

Förfrågningstyp: GET

Förfrågningssökväg: https://password.link/api/secrets

Statuskod för lyckad förfrågan: 200 OK

Hämta en lista över hemligheter. Innehåller inte chiffertexternas privata lösenordsdelar, endast ID:n, beskrivningar och liknande.

Limit och offset

Det maximala antalet returnerade hemligheter för varje förfrågan är begränsat till 50. Du kan kontrollera offset med den valfria offset frågeparameter.

Om du t.ex. vill hoppa över de första 50 posterna använder du en fråga som: .../api/secrets?offset=50

Exempel på fråga

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

Exempel på svar

{
        "data": [
          {
            "id": iD för den hemliga informationen,
            "created_at": när hemligheten skapades,
            "message": meddelandet för hemligheten,
            "description": beskrivningen av hemligheten,
            "view_button": är knappen visa hemlighet aktiverad,
            "captcha": är CAPTCHA aktiverad,
            "password": har hemligheten ett lösenord,
            "expiration": utgångstid i timmar,
            "expired": har hemligheten gått ut,
            "view_times": hur många gånger hemligheten har visats,
            "max_views": maximalt antal gånger hemligheten kan ses,
            "secret_folder_id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
            "views": [
              {
                "viewed_at": en tidsstämpel för när hemligheten visades,
                "viewed_by_ip": IP-adress för visaren,
                "viewed_by_user_agent": användar agent för visaren
              }
            ]
          }
        ],
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Uppdatera Secret

Förfrågningstyp: PATCH

Förfrågningssökväg: https://password.link/api/secrets/<id>

Statuskod för lyckad förfrågan: 204 No Content

Uppdatera stödda inställningar och metadata för ett befintligt Secret. Kräver den privata API-nyckeln. PATCH ersätter inte det krypterade Secret-innehållet, skickar inte om leveransmejl och skapar inte metadata för bilageuppladdning. Använd Skapa Secret för ciphertext, lösenordsdelar, länkleverans och bilagor.

Parametrar för begäran

• description, message, expiration, max_views, view_button, captcha, password: samma betydelse som i Skapa Secret.
• otp_email_recipient, otp_recipient, otp_sms_recipient: samma betydelse som i Skapa Secret.
• allowed_ips, allowed_locations, available_after: samma betydelse som i Skapa Secret.
• secret_folder_id, reply_enabled: samma betydelse som i Skapa Secret.
• ack_required, ack_mode, ack_phrase, ack_disclosure_text, ack_collect_name, ack_name_required, ack_collect_org: samma betydelse som i Skapa Secret.

ciphertext, password_part_private, password_part_public, email_to och bilagemetadata gäller endast vid skapande. De ignoreras av PATCH.

Exempel på fråga

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"}'

Radera hemlighet

Förfrågningstyp: DELETE

Förfrågningssökväg: https://password.link/api/secrets/<id>

Statuskod för lyckad förfrågan: 200 OK

Radera en hemlighet.

Exempel på fråga

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

Exempel på svar

{
        "data": null,
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Hemliga mappar

API-endpoints för Secret-mappar kräver den privata API-nyckel.

Skapa Secret-mapp

Förfrågningstyp: POST

Förfrågningssökväg: https://password.link/api/secret_folders

Statuskod för lyckad förfrågan: 201 Created

• name: mappnamn.
• description (valfri): mappbeskrivning.

Exempel på svar

{
        "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
        }
      }

Lista Secret-mappar

Förfrågningstyp: GET

Förfrågningssökväg: https://password.link/api/secret_folders

Statuskod för lyckad förfrågan: 200 OK

Exempel på svar

{
        "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
        }
      }

Uppdatera Secret-mapp

Förfrågningstyp: PATCH

Förfrågningssökväg: https://password.link/api/secret_folders/<id>

Statuskod för lyckad förfrågan: 204 No Content

Radera hemlig mapp

Förfrågningstyp: DELETE

Förfrågningssökväg: https://password.link/api/secret_folders/<id>

Statuskod för lyckad förfrågan: 200 OK

Skapa hemlig begäran

Typ av begäran: POST

Sökväg för begäran: https://password.link/api/secret_requests

Statuskod för framgångsrik fråga: 201 Created

Skapa en ny hemlig begäran.

Parametrar för begäran

• description: beskrivning för den hemliga begäran.
• message: meddelande för Secret Request-tittaren.
• expiration: utgångstid för den hemliga begäran, i timmar.
• limit: användningsgräns för den hemliga begäran.
• send_request_to_email: skicka den skapade länken för hemlig begäran till den angivna e-postadressen.
• send_request_to_sms: skicka den skapade Secret Request-länken till det angivna telefonnumret.
• send_to_email: skicka den hemliga länken som skapats med hjälp av den hemliga begäran till den angivna e-postadressen.
• secret_description: beskrivning för den hemlighet som skapats med hjälp av hemlighetsbegäran.
• secret_message: meddelande för den hemlighet som skapats med hjälp av hemlighetsbegäran.
• secret_expiration: utgångstid för hemligheten som skapas med den hemliga förfrågan, i timmar.utgångstid i timmar för den hemlighet som skapats med hjälp av hemlighetsbegäran.
• secret_password: lösenord för det Secret som skapats med Secret Request.
• secret_max_views: visningsgräns för den hemlighet som skapats med hjälp av hemlighetsbegäran.
• template_id: ID för begärandemallen som ska användas.
• secret_allowed_emails: kommaavgränsade e-postadresser eller domäner som får öppna Secrets skapade med denna Secret Request.
• secret_allowed_ips: kommaavgränsade IP-adresser eller CIDR-intervall som får öppna Secrets skapade med denna Secret Request.

Exempel på fråga

curl -H "Authorization: ApiKey private_key_abcd" \
        -H "Content-Type: application/json" -X POST https://password.link/api/secret_requests

Exempel på svar

{
        "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
        }
      }

Lista hemliga förfrågningar

Typ av begäran: GET

Sökväg för begäran: https://password.link/api/secret_requests

Statuskod för framgångsrik fråga: 200 OK

Limit och offset

Det maximala antalet returnerade resultat för varje förfrågan är begränsat till 50. Du kan kontrollera offset med den valfria offset-frågeparametern.

Om du t.ex. vill hoppa över de första 50 posterna använder du en fråga som: .../api/secret_requests?offset=50

Listsvaret innehåller inte secret_allowed_emails eller secret_allowed_ips.

Exempel på fråga

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

Exempel på svar

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

Begäran om att ta bort hemlighet

Typ av begäran: DELETE

Sökväg för begäran: https://password.link/api/secret_requests/<id>

Statuskod för framgångsrik fråga: 200 OK

Ta bort en hemlig begäran.

Exempel på fråga

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

Exempel på svar

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