Documentació de l'API

General

Tenim una API REST estàndard per gestionar secrets. Totes les sol·licituds i respostes utilitzen el JSON format.

Podeu utilitzar l'API per gestionar tant l'encriptació com la desencriptació del secret fora del nostre servei, sense necessitat de carregar cap actiu de la nostra part. També permet utilitzar qualsevol tipus de mètode de lliurament per a la part pública de la contrasenya (meitat de la contrasenya que s'utilitza per derivar la clau d'encriptació per al secret) i bàsicament crear qualsevol tipus de configuració personalitzada per visualitzar el secret.

Exemples de codi

Si us plau, consulteu els nostres exemples d'API sobre com utilitzar l'API.

Autenticació

Fem servir dos tipus de claus API per a l'autenticació:

  • Claus API públiques
  • Claus API privades

Les claus API públiques estan destinades a crear una pàgina secreta de visualització personalitzada auto-hostejada. Totes les altres accions de l'API requereixen una clau API privada.

Les claus API públiques es poden utilitzar en scripts públics. Les claus API privades sempre han de mantenir-se privades.

Ambdues claus API contenen el tipus de clau dins de la pròpia clau, de manera que es poden distingir fàcilment.

La clau API s'ha d'enviar en el Authorization: ApiKey <key> capçalera, com:

Authorization: ApiKey public_key_abc...

Errors

En cas de consulta sense èxit, la resposta tindrà un error objecte.

L'objecte conté els següents camps:

  • missatge: el missatge d'error complet, per exemple "El text xifrat no pot estar buit"
  • camp: el camp del qual es tracta l'error, per exemple "text xifrat"

El codi d'estat de resposta HTTP també indicarà un error, per exemple:

  • 403 Prohibit: la sol·licitud no estava permesa, per exemple a causa d'una clau API no vàlida
  • 404 No trobat: el secret sol·licitat no s'ha trobat

Veure Secret

Tipus de sol·licitud: GET

Camí de sol·licitud: https://password.link/api/secrets/<id>

Codi d'estat de la consulta exitosa: 200 OK


Obtenir el text xifrat, la part de contrasenya privada i altres detalls d'un secret. Requereix el públic clau API.

Aquesta consulta d'API es pot utilitzar per crear una pàgina de secret de visualització personalitzada auto-hostejada que no carrega cap script ni altres actius del nostre servei.

Obtenir un secret amb èxit el marca automàticament com a vist i, per tant, elimina el text xifrat i la part de contrasenya privada de la nostra base de dades, fent impossible veure el secret de nou.

Paràmetres requerits
  • id: l'id del secret, per exemple dT5g

exemple de consulta

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

exemple de resposta

{
        "data": {
          "id": "la ID del secret",
          "ciphertext": "el text xifrat del secret",
          "password_part_private": "la part de contrasenya privada del secret",
          "message": "el missatge per al secret, si s'ha establert"
        },
        "metadata": null
      }

Exemple de codi

Si us plau, consulteu els nostres exemples d'API.

Crear Secret

Tipus de sol·licitud: POST

Camí de sol·licitud: https://password.link/api/secrets

Codi d'estat de la consulta exitosa: 201 Created

Aquesta crida d'API també permet afegir un fitxer adjunt xifrat al secret.


Crea un secret xifrat.

Xifrar el secret al costat del client abans d'enviar-lo a la nostra API requereix crear una cadena JSON de xifrat compatible amb SJCL. Si us plau, consulteu el <a href=\"https://github.com/bitwiseshiftleft/sjcl\">Documentació de SJCL</a> per al format adequat de la cadena JSON, i consulteu els nostres <a href=\"/p/docs/api/examples\">Exemples d'API</a> per a exemples sobre com crear el xifrat.

Creant la contrasenya per xifrar el secret

La contrasenya que s'utilitza per xifrar el secret en AES ha de consistir en dues cadenes de 18 caràcters de longitud. La clau de xifrat real serà la concatenació d'aquestes dues cadenes ("part privada" + "part pública") i es deriva de la contrasenya per SJCL mitjançant PBKDF2.

Exemple de creació de les parts de contrasenya privada i pública:

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

La part privada ha de ser codificada en Base64 abans d'enviar-la a la nostra API. Si utilitzeu la pàgina de visualització de secrets proporcionada per nosaltres, també heu de codificar en Base64 la part pública. Si utilitzeu una pàgina de visualització de secrets autohostejada, podeu utilitzar el mateix mètode o crear el vostre propi. Si us plau, consulteu les nostres <a href=\"/p/docs/api/examples\">Exemples d'API</a> per a implementacions de referència.

Configuracions SJCL AES requerides

Heu d'utilitzar les següents configuracions per a AES quan xifreu el secret:

  • Mode: AES-GCM (Configuraicó SJCL:"mode:gcm")
  • Mida de la clau: 256 bits (Configuraicó SJCL:"ks:256")
  • Funció de derivació de claus: PBKDF2 (Por defecte de SJCL)
  • Iteracions de PBKDF2: 10000 (Configuració de SJCL: "iter:10000")

Payload de la sol·licitud

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

Paràmetres de la sol·licitud.

  • ciphertext: Una cadena JSON de xifrat compatible amb SJCL del secret, codificada en Base64.
  • password_part_private: la part de contrasenya privada que es va utilitzar per xifrar el secret, en Base64.
  • password_part_public (opcional): la part pública de la contrasenya, en Base64. Només és obligatori quan s'utilitza email_to perquè l'API pugui enviar per correu l'enllaç del Secret allotjat.
  • description (opcional): una descripció per al secret. No es pot veure quan es visualitza el secret.
  • message (opcional): un missatge per al secret. Es mostrarà juntament amb el secret.
  • expiration (opcional): un temps d'expiració per al secret, en hores. Valors possibles: 1-500.
  • view_button (opcional): mostrar un botó de veure el secret en comptes de mostrar el secret immediatament després d'obrir l'enllaç. Per activar aquesta funció, estableix-ho a true.
  • captcha (opcional): mostrar un CAPTCHA simple abans de mostrar el secret, principalment per bloquejar escàners automatitzats. Per activar aquesta funció, estableix-ho a true.
  • password (opcional): una contrasenya per al secret.
  • max_views (opcional): quantes vegades es pot veure el secret. Valors possibles: 1-100.
  • email_to (opcional): destinataris de correu separats per comes que han de rebre l'enllaç del Secret creat. Requereix password_part_public.
  • otp_email_recipient (opcional): adreça de correu que rep una contrasenya d'un sol ús. Quan s'estableix, el destinatari ha d'introduir el codi enviat per correu abans que es pugui veure el Secret.
  • otp_recipient (opcional): s'accepta com a àlies de otp_email_recipient. Preferiu otp_email_recipient per a integracions noves.
  • otp_sms_recipient (opcional): número de telèfon que rep una contrasenya d'un sol ús per SMS, en format internacional que comença per + i sense espais.
  • allowed_ips (opcional): adreces IP o intervals CIDR separats per comes autoritzats a veure el Secret.
  • allowed_locations (opcional): array de codis de país ISO 3166-1 alfa-2 autoritzats a veure el Secret.
  • available_after (opcional): data i hora abans de les quals no es pot veure el Secret.
  • secret_folder_id (opcional): ID d'una carpeta de Secrets existent propietat de l'usuari de la clau API.
  • reply_enabled (opcional): habilitar una resposta d'un sol ús del destinatari després que s'hagi vist el Secret.
  • ack_required (opcional): requerir confirmació del destinatari abans que es pugui veure el Secret.
  • ack_mode (opcional): mode de confirmació. Utilitzeu checkbox o phrase.
  • ack_phrase (obligatori quan ack_required és true i ack_mode és phrase): frase que el destinatari ha d'escriure.
  • ack_disclosure_text (opcional): text de divulgació mostrat al destinatari, fins a 500 caràcters.
  • ack_collect_name (opcional): recollir el nom del destinatari amb la confirmació.
  • ack_name_required (opcional): requerir el nom del destinatari. Això també habilita ack_collect_name.
  • ack_collect_org (opcional): recollir l'organització del destinatari amb la confirmació.
  • attachment (opcional): metadades per a un fitxer adjunt xifrat. Requereix un pla actiu. El fitxer xifrat es carrega per separat després que s'hagi creat el secret.
  • attachment.file_name (obligatori quan es proporciona un adjunt): el nom de fitxer original que es mostra al destinatari.
  • attachment.file_type (obligatori quan es proporciona un adjunt): el tipus MIME original, per exemple text/plain o application/pdf.
  • attachment.file_size (obligatori quan es proporciona un adjunt): la mida original sense xifrar del fitxer en bytes.

La configuració de Secrets de l'equip pot desactivar, requerir o imposar valors predeterminats per a les opcions de Secret compatibles. L'API aplica aquestes regles de l'equip quan crea un Secret.

Carregar un fitxer adjunt

Carregar un fitxer adjunt és un procés de dos passos: primer creeu el secret amb les metadades de l'adjunt, després xifreu i carregueu la càrrega útil xifrada de l'adjunt a l'URL de càrrega retornada.

El contingut del secret i el contingut de l'adjunt es xifren per separat. El text xifrat del secret són dades AES-GCM compatibles amb SJCL, codificades en Base64. L'adjunt es xifra amb dades AES-GCM compatibles amb Web Crypto i després es codifica en Base64.

La contrasenya de xifrat de l'adjunt és la part privada bruta de la contrasenya concatenada amb la part pública bruta de la contrasenya: <raw private password part> + <raw public password part>.

Quan s'inclou un adjunt, la resposta de creació del secret conté una destinació de càrrega a data.attachment.upload:

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

Les URL de càrrega allotjades a Password.link inclouen un objecte fields buit. Les URL de càrrega directa a emmagatzematge, com les URL S3 pre-signades, retornen els camps de signatura a metadata.

Abans del xifrat, representeu el fitxer com una URL de dades: data:<mime-type>;base64,<base64 file bytes>.

Xifreu aquesta cadena d'URL de dades amb AES-GCM utilitzant PBKDF2-SHA256, 10000 iteracions, una clau derivada de 256 bits, una sal aleatòria de 16 bytes i un IV aleatori de 12 bytes. Emmagatzemeu la càrrega xifrada de l'adjunt com un objecte JSON que contingui cipher, iv i salt, i després codifiqueu la cadena JSON en Base64.

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

Carregueu el JSON xifrat codificat en Base64 com a text/plain utilitzant multipart/form-data a l'URL retornada upload.url. Afegiu tots els upload.metadata o upload.fields parells clau/valor retornats a les dades del formulari abans d'afegir el fitxer xifrat. El camp del fitxer xifrat s'ha d'anomenar file.

Per als URL de càrrega de Password.link, incloeu la mateixa clau d'API privada a la capçalera Authorization: ApiKey <key>. Els URL de càrrega directa a l'emmagatzematge, com ara URL S3 presignats, només han de rebre els camps de formulari retornats i el camp file xifrat.

La resposta de creació de secret de l'API retorna una destinació de càrrega d'adjunt per a l'únic paràmetre attachment . Els límits de mida dels adjunts depenen de l'assignació del compte o de l'equip, i la càrrega xifrada és més gran que el fitxer original perquè el fitxer es converteix a Base64 i es xifra.

Exemple de codi

Si us plau, consulteu els nostres exemples d'API.

Confirmar Secret

Tipus de sol·licitud: POST

Camí de sol·licitud: https://password.link/api/secrets/<id>/acknowledge

Codi d'estat de la consulta exitosa: 200 OK


Enviar la confirmació del destinatari per a un Secret creat amb ack_required. Requereix la públic clau API i retorna les mateixes dades del Secret que Veure Secret quan la confirmació és vàlida.

Si cal confirmació, GET /api/secrets/<id> retorna 403 Forbidden amb secret_status establert a ack_required fins que s'utilitzi aquest endpoint.

Les càrregues de confirmació no vàlides o incompletes també retornen 403 Forbidden. No es retornen com a errors de validació.

Paràmetres de la sol·licitud.

  • ack_confirmed: establert a true per a la confirmació amb casella.
  • ack_phrase: obligatori per a la confirmació amb frase, i ha de coincidir amb la frase configurada per al Secret.
  • ack_signer_name: nom del destinatari, obligatori quan la recollida de nom està habilitada i marcada com a obligatòria.
  • ack_signer_org: organització del destinatari, desada quan la recollida d'organització està habilitada.

exemple de consulta

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

exemple de resposta

{
        "data": {
          "id": "la ID del secret",
          "ciphertext": "el text xifrat del secret",
          "password_part_private": "la part de contrasenya privada del secret",
          "message": "el missatge per al secret, si s'ha establert"
        },
        "metadata": null
      }

Llistar Secrets

Tipus de sol·licitud: GET

Camí de sol·licitud: https://password.link/api/secrets

Codi d'estat de la consulta exitosa: 200 OK


Obteniu una llista de secrets. No conté les parts de contrasenya privada dels textos xifrats, només IDs, descripcions i coses similars.

Limit i offset

La quantitat màxima de secrets retornats per a cada consulta està limitada a 50. Podeu controlar l'offset amb l'opcional offset paràmetre de consulta.

Per exemple, per saltar els primers 50 registres, utilitzeu una consulta com aquesta: .../api/secrets?offset=50

exemple de consulta

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

exemple de resposta

{
        "data": [
          {
            "id": la ID del secret,
            "created_at": quan es va crear el secret,
            "message": el missatge per al secret,
            "description": la descripció del secret,
            "view_button": està habilitat el botó de veure el secret,
            "captcha": està habilitat el CAPTCHA,
            "password": té el secret una contrasenya,
            "expiration": temps d'expiració en hores,
            "expired": ha expirat el secret,
            "view_times": quantes vegades s'ha vist el secret,
            "max_views": la quantitat màxima de vegades que es pot veure el secret,
            "secret_folder_id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
            "views": [
              {
                "viewed_at": una marca de temps de quan es va veure el secret,
                "viewed_by_ip": adreça IP de l'espectador,
                "viewed_by_user_agent": agent d'usuari de l'espectador
              }
            ]
          }
        ],
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Actualitzar Secret

Tipus de sol·licitud: PATCH

Camí de sol·licitud: https://password.link/api/secrets/<id>

Codi d'estat de la consulta exitosa: 204 No Content


Actualitzar opcions i metadades compatibles d'un Secret existent. Requereix la privada clau API. PATCH no substitueix el contingut xifrat del Secret, no torna a enviar correus de lliurament ni crea metadades de pujada d'adjunts. Utilitzeu Crear Secret per al ciphertext, parts de contrasenya, lliurament d'enllaços i adjunts.

Paràmetres de la sol·licitud.

  • description, message, expiration, max_views, view_button, captcha, password: mateix significat que a Crear Secret.
  • otp_email_recipient, otp_recipient, otp_sms_recipient: mateix significat que a Crear Secret.
  • allowed_ips, allowed_locations, available_after: mateix significat que a Crear Secret.
  • secret_folder_id, reply_enabled: mateix significat que a Crear Secret.
  • ack_required, ack_mode, ack_phrase, ack_disclosure_text, ack_collect_name, ack_name_required, ack_collect_org: mateix significat que a Crear Secret.

ciphertext, password_part_private, password_part_public, email_to i les metadades d'adjunts són només de creació. PATCH les ignora.

exemple de consulta

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

Esborrar Secret

Tipus de sol·licitud: DELETE

Camí de sol·licitud: https://password.link/api/secrets/<id>

Codi d'estat de la consulta exitosa: 200 OK


Esborrar un secret.

exemple de consulta

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

exemple de resposta

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

Carpetes secretes

Els endpoints de l'API de carpetes de Secrets requereixen la privada clau API.

Crear carpeta de Secrets

Tipus de sol·licitud: POST

Camí de sol·licitud: https://password.link/api/secret_folders

Codi d'estat de la consulta exitosa: 201 Created

  • name: nom de la carpeta.
  • description (opcional): descripció de la carpeta.

exemple de resposta

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

Llistar carpetes de Secrets

Tipus de sol·licitud: GET

Camí de sol·licitud: https://password.link/api/secret_folders

Codi d'estat de la consulta exitosa: 200 OK

exemple de resposta

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

Actualitzar carpeta de Secrets

Tipus de sol·licitud: PATCH

Camí de sol·licitud: https://password.link/api/secret_folders/<id>

Codi d'estat de la consulta exitosa: 204 No Content

Eliminar carpeta secreta

Tipus de sol·licitud: DELETE

Camí de sol·licitud: https://password.link/api/secret_folders/<id>

Codi d'estat de la consulta exitosa: 200 OK

Crea una sol·licitud de secret

Tipus de sol·licitud: POST

Ruta de sol·licitud: https://password.link/api/secret_requests

Codi d'estat de la consulta reeixida.: 201 Created


Crea una nova sol·licitud de secret.

Paràmetres de la sol·licitud.

  • description: Descripció de la sol·licitud de secret.
  • message: Missatge per al visualitzador de la sol·licitud de secret.
  • expiration: Temps d'expiració de la sol·licitud de secret, en hores.
  • limit: Límit d'ús per a la sol·licitud de secret.
  • send_request_to_email: Envia l'enllaç de la sol·licitud de secret creada a l'adreça de correu electrònic proporcionada.
  • send_request_to_sms: enviar l'enllaç de Secret Request creat al número de telèfon indicat.
  • send_to_email: envia l'enllaç secret creat utilitzant la sol·licitud secret a l'adreça de correu electrònic proporcionada.
  • secret_description: descripció per al secret creat utilitzant la sol·licitud secret.
  • secret_message: missatge per al secret creat utilitzant la sol·licitud secret.
  • secret_expiration: temps d'expiració per al secret creat utilitzant la sol·licitud secret, en hores.
  • secret_password: contrasenya per al Secret creat amb el Secret Request.
  • secret_max_views: límit de visualització per al secret creat utilitzant la sol·licitud secret.
  • template_id: ID de la plantilla de sol·licitud que s'ha d'utilitzar.
  • secret_allowed_emails: adreces de correu o dominis separats per comes autoritzats a obrir Secrets creats amb aquest Secret Request.
  • secret_allowed_ips: adreces IP o intervals CIDR separats per comes autoritzats a obrir Secrets creats amb aquest Secret Request.

exemple de consulta

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

exemple de resposta

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

Llista de sol·licituds secretes

Tipus de sol·licitud: GET

Ruta de sol·licitud: https://password.link/api/secret_requests

Codi d'estat de la consulta reeixida.: 200 OK


Limit i offset

La quantitat màxima de resultats retornats per a cada consulta està limitada a 50. Podeu controlar l'offset amb el paràmetre de consulta opcional offset.

Per exemple, per saltar els primers 50 registres, utilitzeu una consulta com aquesta: .../api/secret_requests?offset=50

La resposta de llista no inclou secret_allowed_emails o secret_allowed_ips.

exemple de consulta

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

exemple de resposta

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

Esborra la sol·licitud secreta

Tipus de sol·licitud: DELETE

Ruta de sol·licitud: https://password.link/api/secret_requests/<id>

Codi d'estat de la consulta reeixida.: 200 OK


Esborra una sol·licitud secreta.

exemple de consulta

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

exemple de resposta

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