API-dokumentation

Översikt

Bas-URL:en för alla API-slutpunkter är:

https://password.link/api

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.

För fungerande komplett kod, se Exempel på API.

Autentisering

Varje förfrågan måste autentiseras med en API-nyckel som skickas i Authorization-huvudet:

Authorization: ApiKey public_key_abcd...

Det finns två typer av API-nycklar:

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

Varje slutpunkt nedan visar vilken nyckeltyp den kräver.

Fel

När en förfrågan misslyckas innehåller svaret ett felobjekt:

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

HTTP-svarets statuskod anger också typen av fel:

Kryptering av hemligheter

Hemligheter krypteras på klientsidan innan de skickas till API:et. Det här avsnittet beskriver de lösenords- och chiffertextformat som tjänsten förväntar sig.

Lösenordsdelarna

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 med PBKDF2.

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

Den privata delen skickas till API:et (Base64-kodad) och lagras med hemligheten. Den publika delen skickas aldrig till API:et och levereras vanligtvis i själva länken, så vi kan aldrig dekryptera hemligheten själva.

Om du använder sidan för att visa hemligheter som vi tillhandahåller måste du också Base64-koda den publika delen. Om du använder en självhostad visningssida kan du använda samma metod eller skapa en egen. Se Exempel på API för referensimplementationer.

Chiffertextens format

Chiffertexten är ett JSON-objekt, kodat i Base64:

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

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

Äldre SJCL-format (föråldrat)

Dekryptering av hemligheter

API:et Visa hemlighet returnerar chiffertexten exakt som den lagrades. Hemligheter som skapas i webbappen använder Web Crypto-formatet ovan. Hemligheter som skapats av äldre API-klienter, Chrome-tillägget eller ännu oöppnade länkar kan använda det äldre SJCL-formatet.

En självhostad visningssida måste hantera båda formaten. Avkoda chiffertexten från Base64 till JSON och kontrollera sedan om det finns en ct-nyckel: om den finns, dekryptera med SJCL, annars med Web Crypto. Se exemplet Visa hemlighet.

Skapa hemlighet

Skapar en krypterad hemlighet och returnerar dess ID. Chiffertexten måste skapas enligt beskrivningen i Kryptering av hemligheter. Returnerar 201 Created vid framgång.

Parametrar för begäran

Exempel på förfrågan

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

Exempel på svar

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

Länken till hemligheten bildas genom att kombinera URL:en till den hostade visningssidan, hemlighetens ID och den Base64-kodade publika lösenordsdelen:

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

Bilagor

Att ladda upp en bilaga är en process i två steg: skapa först hemligheten med bilagans metadata (se Skapa hemlighet), kryptera sedan och ladda upp den krypterade bilagenyttolasten till den returnerade uppladdnings-URL:en.

Hemlighetens innehåll och bilagans innehåll krypteras separat. Båda använder Web Crypto-kompatibla AES-GCM-data, Base64-kodade, men nyttolastens fält kodas olika: hemlighetens nyttolast innehåller Base64-kodade fält och ett iter-fält, medan bilagans nyttolast innehåller fält med råa binära strängar.

Kryptering av bilagan

Före kryptering representerar du filen som en data-URL:

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

Bilagans krypteringslösenord är den råa privata lösenordsdelen sammanfogad med den råa publika lösenordsdelen (ingen Base64-kodning).

Kryptera den data-URL-strängen med AES-GCM med PBKDF2-SHA256, 10000 iterationer, en härledd 256-bitars nyckel, ett slumpmässigt 16-byte salt och en slumpmässig 12-byte IV. Lagra den krypterade bilagenyttolasten som ett JSON-objekt och Base64-koda sedan JSON-strängen:

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

Uppladdning av den krypterade filen

När en bilaga ingår 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": {}
}

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 nyckel/värde-par från upload.metadata eller upload.fields i formulärdatan 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.

Visa hemlighet

Hämtar chiffertexten, den privata lösenordsdelen och andra detaljer om en hemlighet. Den här slutpunkten kan användas för att skapa en egen självhostad sida för att visa hemligheter som inte läser in några skript eller andra resurser från vår tjänst. Returnerar 200 OK vid framgång.

Om hemligheten är skyddad med en OTP-kod eller ett lösenord, skicka värdet i ett begäranshuvud. Värden i frågesträngen accepteras inte. Utan ett giltigt värde returneras 403 Forbidden med secret_status satt till otp_required eller password_required. Om en hemlighet har både en OTP-mottagare och ett lösenord kontrolleras endast OTP-koden, på samma sätt som när hemligheten öppnas i en webbläsare.

OTP-koden skickas till OTP-mottagaren när denne öppnar länken till hemligheten. API:et skickar den inte. Hemligheter som endast begränsar tillåtna mottagares e-postadresser kräver ingen OTP-kod via API:et.

Begäranshuvuden

Exempel på förfrågan

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

Exempel på svar

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

Bekräfta Secret

Skickar mottagarens bekräftelse för en hemlighet som skapats med ack_required och returnerar samma hemlighetsdata som View Secret när bekräftelsen är giltig. Returnerar 200 OK vid framgång.

Om bekräftelse krävs returnerar GET /api/secrets/<id> 403 Forbidden med secret_status satt till ack_required tills den här slutpunkten används.

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

Om hemligheten är skyddad med en OTP-kod eller ett lösenord, skicka värdet i samma huvuden som för ”Visa hemlighet”, eller som otp och password i JSON-begärans brödtext.

Parametrar för begäran

Exempel på förfrågan

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

Lista hemligheter

Hämtar en lista över hemligheter. Innehåller inte chiffertexterna eller de privata lösenordsdelarna, endast ID:n, beskrivningar och liknande. Returnerar 200 OK vid framgång.

Det maximala antalet returnerade resultat för varje fråga är begränsat till 50. Du kan styra offseten med den valfria frågeparametern offset, till exempel: /api/secrets?offset=50

Exempel på förfrågan

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

Exempel på svar

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

Uppdatera Secret

Uppdaterar inställningar och metadata som stöds för en befintlig hemlighet. Returnerar 204 No Content vid framgång.

PATCH ersätter inte hemlighetens krypterade innehåll, skickar inte om leverans-e-post och skapar inte metadata för bilageuppladdning. Använd Create Secret för chiffertext, lösenordsdelar, länkleverans och bilagor.

Följande parametrar kan uppdateras, med samma betydelse som i 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

Exempel på förfrågan

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

Raderar en hemlighet. Returnerar 200 OK vid framgång.

Exempel på förfrågan

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

Exempel på svar

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

Skapa Secret-mapp

Skapar en hemlighetsmapp. Returnerar 201 Created vid framgång.

Parametrar för begäran

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

Hämtar en lista över hemlighetsmappar. Returnerar 200 OK vid framgång.

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

Uppdaterar namnet och beskrivningen för en hemlighetsmapp. Accepterar samma parametrar som Create Secret Folder och returnerar 204 No Content vid framgång.

Radera hemlig mapp

Raderar en hemlighetsmapp. Returnerar 200 OK vid framgång.

Skapa hemlig begäran

Skapar en ny hemlig begäran. Returnerar 201 Created vid framgång.

Parametrar för begäran

Exempel på förfrågan

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

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

Hämtar en lista över hemliga begäranden. Returnerar 200 OK vid framgång.

Det maximala antalet returnerade resultat för varje fråga är begränsat till 50. Du kan styra offseten med den valfria frågeparametern offset, till exempel: /api/secret_requests?offset=50

Listsvaret innehåller inte secret_allowed_emails eller secret_allowed_ips.

Exempel på förfrågan

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

Exempel på svar

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

Begäran om att ta bort hemlighet

Raderar en hemlig begäran. Returnerar 200 OK vid framgång.

Exempel på förfrågan

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