Documentació de l'API

Visió general

L'URL base per a tots els punts finals de l'API és:

https://password.link/api

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.

Per a codi complet i funcional, consulteu els Exemples d'API.

Autenticació

Cada sol·licitud s'ha d'autenticar amb una clau d'API, enviada a la capçalera Authorization:

Authorization: ApiKey public_key_abcd...

Hi ha dos tipus de claus d'API:

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

Cada punt final a continuació mostra quin tipus de clau requereix.

Errors

Quan una sol·licitud falla, la resposta conté un objecte d'error:

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

El codi d'estat HTTP de la resposta també indica el tipus d'error:

Xifratge de secrets

Els secrets es xifren al costat del client abans d'enviar-se a l'API. Aquesta secció descriu els formats de contrasenya i de text xifrat que espera el servei.

Les parts de la contrasenya

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 mitjançant PBKDF2.

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

La part privada s'envia a l'API (codificada en Base64) i s'emmagatzema amb el secret. La part pública mai s'envia a l'API i normalment es lliura al mateix enllaç, de manera que nosaltres mai podem desxifrar el secret.

Si utilitzeu la pàgina de visualització del secret que us proporcionem, també heu de codificar la part pública en Base64. Si utilitzeu una pàgina de visualització autoallotjada, podeu utilitzar el mateix mètode o crear-ne un de propi. Consulteu els Exemples d'API per a implementacions de referència.

Format del text xifrat

El text xifrat és un objecte JSON, codificat en Base64:

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

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

Format SJCL antic (obsolet)

Desxifratge de secrets

L'API Veure Secret retorna el text xifrat exactament tal com es va emmagatzemar. Els secrets creats a l'aplicació web utilitzen el format Web Crypto descrit més amunt. Els secrets creats per clients de l'API antics, per l'extensió de Chrome o per enllaços encara no oberts poden utilitzar el format SJCL antic.

Una pàgina de visualització autoallotjada ha de gestionar tots dos formats. Després de descodificar el text xifrat de Base64 a JSON, comproveu si hi ha una clau ct: si hi és, desxifreu amb SJCL; en cas contrari, desxifreu amb Web Crypto. Vegeu l'exemple de Veure Secret.

Crear Secret

Crea un secret xifrat i en retorna l'ID. El text xifrat s'ha de crear tal com es descriu a Xifratge de secrets. Retorna 201 Created en cas d'èxit.

Paràmetres de la sol·licitud.

Exemple de sol·licitud

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

Exemple de resposta

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

L'enllaç al secret es forma combinant l'URL de la pàgina de visualització allotjada, l'ID del secret i la part pública de la contrasenya codificada en Base64:

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

Adjunts

Carregar un fitxer adjunt és un procés de dos passos: primer creeu el secret amb les metadades del fitxer adjunt (vegeu Crear Secret), després xifreu i carregueu la càrrega xifrada del fitxer adjunt a l'URL de càrrega retornat.

El contingut del secret i el contingut de l'adjunt es xifren per separat. Tots dos utilitzen dades AES-GCM compatibles amb Web Crypto, codificades en Base64, però els camps de la càrrega útil es codifiquen de manera diferent: la càrrega útil del secret conté camps codificats en Base64 i un camp iter, mentre que la càrrega útil de l'adjunt conté camps de cadenes binàries en brut.

Xifratge del fitxer adjunt

Abans del xifrat, representeu el fitxer com una URL de dades:

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

La contrasenya de xifratge del fitxer adjunt és la part privada en brut de la contrasenya concatenada amb la part pública en brut (sense codificació Base64).

Xifreu aquesta cadena data URL 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. Deseu la càrrega xifrada del fitxer adjunt com un objecte JSON i després codifiqueu la cadena JSON en Base64:

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

Càrrega del fitxer xifrat

Quan s'inclou un fitxer 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": {}
}

Carregueu el JSON xifrat codificat en Base64 com a text/plain utilitzant multipart/form-data a l'upload.url retornat. Afegiu tots els parells clau/valor retornats a upload.metadata o upload.fields 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.

Veure Secret

Obté el text xifrat, la part privada de la contrasenya i altres detalls d'un secret. Aquest punt final es pot utilitzar per crear una pàgina personalitzada i autoallotjada per veure el secret que no carrega scripts ni altres recursos del nostre servei. Retorna 200 OK en cas d'èxit.

Si el secret està protegit amb un codi OTP o una contrasenya, envieu-lo en una capçalera de la sol·licitud. No s'accepten valors a la cadena de consulta. Sense un valor vàlid, es retorna 403 Forbidden amb secret_status establert a otp_required o password_required. Si un secret té tant un destinatari d'OTP com una contrasenya, només es comprova el codi OTP, igual que quan el secret s'obre en un navegador.

El codi OTP s'envia al destinatari OTP quan obre l'enllaç del secret. L'API no l'envia. Els secrets que només restringeixen les adreces de correu electrònic dels destinataris permesos no requereixen cap codi OTP a través de l'API.

Capçaleres de la sol·licitud

Exemple de sol·licitud

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

Exemple de resposta

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

Confirmar Secret

Envia la confirmació del destinatari per a un secret creat amb ack_required i retorna les mateixes dades del secret que View Secret quan la confirmació és vàlida. Retorna 200 OK en cas d'èxit.

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

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

Si el secret està protegit amb un codi OTP o una contrasenya, envieu-lo a les mateixes capçaleres que a «Veure Secret», o com a otp i password al cos JSON de la sol·licitud.

Paràmetres de la sol·licitud.

Exemple de sol·licitud

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

Llistar Secrets

Obté una llista de secrets. No conté els textos xifrats ni les parts privades de les contrasenyes, només IDs, descripcions i similars. Retorna 200 OK en cas d'èxit.

La quantitat màxima de resultats retornats per a cada consulta està limitada a 50. Podeu controlar el desplaçament amb el paràmetre de consulta opcional offset, per exemple: /api/secrets?offset=50

Exemple de sol·licitud

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

Exemple de resposta

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

Actualitzar Secret

Actualitza la configuració i les metadades compatibles d'un secret existent. Retorna 204 No Content en cas d'èxit.

PATCH no substitueix el contingut xifrat del secret, no torna a enviar correus de lliurament ni crea metadades de càrrega de fitxers adjunts. Utilitzeu Create Secret per al text xifrat, les parts de la contrasenya, el lliurament de l'enllaç i els fitxers adjunts.

Els paràmetres següents es poden actualitzar, amb el mateix significat que a 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

Exemple de sol·licitud

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

Elimina un secret. Retorna 200 OK en cas d'èxit.

Exemple de sol·licitud

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

Exemple de resposta

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

Crear carpeta de Secrets

Crea una carpeta de secrets. Retorna 201 Created en cas d'èxit.

Paràmetres de la sol·licitud.

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

Obté una llista de carpetes de secrets. Retorna 200 OK en cas d'èxit.

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

Actualitza el nom i la descripció d'una carpeta de secrets. Accepta els mateixos paràmetres que Create Secret Folder i retorna 204 No Content en cas d'èxit.

Eliminar carpeta secreta

Elimina una carpeta de secrets. Retorna 200 OK en cas d'èxit.

Crea una sol·licitud de secret

Crea una nova sol·licitud de secret. Retorna 201 Created en cas d'èxit.

Paràmetres de la sol·licitud.

Exemple de sol·licitud

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

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

Obté una llista de sol·licituds de secret. Retorna 200 OK en cas d'èxit.

La quantitat màxima de resultats retornats per a cada consulta està limitada a 50. Podeu controlar el desplaçament amb el paràmetre de consulta opcional offset, per exemple: /api/secret_requests?offset=50

La resposta de la llista no inclou secret_allowed_emails ni secret_allowed_ips.

Exemple de sol·licitud

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

Exemple de resposta

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

Esborra la sol·licitud secreta

Elimina una sol·licitud de secret. Retorna 200 OK en cas d'èxit.

Exemple de sol·licitud

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