Documentazione API

Panoramica

L'URL di base per tutti gli endpoint dell'API è:

https://password.link/api

È possibile utilizzare l'API per gestire sia la crittografia che la decrittografia del segreto al di fuori del nostro servizio, senza dover caricare alcuna risorsa da noi. Inoltre, è possibile utilizzare qualsiasi tipo di metodo di consegna per la parte della password pubblica (metà della password che viene utilizzata per ricavare la chiave di crittografia del segreto) e, in pratica, creare qualsiasi tipo di configurazione personalizzata per la visualizzazione del segreto.

Per un codice completo e funzionante, consultate gli Esempi di API.

Autenticazione

Ogni richiesta deve essere autenticata con una chiave API, inviata nell'header Authorization:

Authorization: ApiKey public_key_abcd...

Esistono due tipi di chiavi API:

Entrambe le chiavi API contengono il tipo di chiave nella chiave stessa, in modo da poterle distinguere facilmente.

Ogni endpoint qui sotto indica quale tipo di chiave richiede.

Errori

Quando una richiesta fallisce, la risposta contiene un oggetto di errore:

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

Il codice di stato HTTP della risposta indica anche il tipo di errore:

Crittografia dei segreti

I segreti vengono crittografati lato client prima di essere inviati all'API. Questa sezione descrive i formati della password e del testo cifrato attesi dal servizio.

Le parti della password

La password utilizzata per criptare il segreto in AES deve essere composta da due stringhe di 18 caratteri. La chiave di crittografia vera e propria sarà la concatenazione di queste due stringhe ("parte privata" + "parte pubblica") ed è derivata dalla password utilizzando PBKDF2.

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

La parte privata viene inviata all'API (codificata in Base64) e memorizzata con il segreto. La parte pubblica non viene mai inviata all'API e di solito viene consegnata nel link stesso, quindi noi non possiamo mai decrittografare il segreto.

Se utilizzate la pagina di visualizzazione del segreto fornita da noi, dovete codificare in Base64 anche la parte pubblica. Se utilizzate una pagina di visualizzazione self-hosted, potete usare lo stesso metodo o crearne uno vostro. Consultate gli Esempi di API per implementazioni di riferimento.

Formato del testo cifrato

Il testo cifrato è un oggetto JSON, codificato in Base64:

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

Per la crittografia del segreto è necessario utilizzare le seguenti impostazioni per AES:

Formato SJCL legacy (deprecato)

Decrittografia dei segreti

L'API Visualizza il Segreto restituisce il testo cifrato esattamente come è stato memorizzato. I segreti creati nell'applicazione web utilizzano il formato Web Crypto descritto sopra. I segreti creati da client API più vecchi, dall'estensione per Chrome o da link ancora non aperti possono utilizzare il formato SJCL legacy.

Una pagina di visualizzazione self-hosted deve gestire entrambi i formati. Dopo aver decodificato il testo cifrato da Base64 a JSON, verificare la presenza di una chiave ct: se è presente, decrittografare con SJCL, altrimenti decrittografare con Web Crypto. Vedere l'esempio Visualizza il Segreto.

Creare un segreto

Crea un segreto crittografato e ne restituisce l'ID. Il testo cifrato deve essere creato come descritto in Crittografia dei segreti. Restituisce 201 Created in caso di successo.

Parametri della richiesta

Esempio di richiesta

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

Esempio di risposta

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

Il link al segreto si forma combinando l'URL della pagina di visualizzazione ospitata, l'ID del segreto e la parte pubblica della password codificata in Base64:

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

Allegati

Il caricamento di un allegato è un processo in due fasi: prima si crea il segreto con i metadati dell'allegato (vedere Creare un segreto), poi si crittografa e si carica il payload crittografato dell'allegato all'URL di caricamento restituito.

Il contenuto del segreto e il contenuto dell'allegato vengono crittografati separatamente. Entrambi utilizzano dati AES-GCM compatibili con Web Crypto, codificati in Base64, ma i campi del payload sono codificati in modo diverso: il payload del segreto contiene campi codificati in Base64 e un campo iter, mentre il payload dell'allegato contiene campi di stringhe binarie grezze.

Crittografia dell'allegato

Prima della crittografia, rappresenta il file come URL di dati:

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

La password di crittografia dell'allegato è la parte privata grezza della password concatenata con la parte pubblica grezza (senza codifica Base64).

Crittografate quella stringa data URL con AES-GCM usando PBKDF2-SHA256, 10000 iterazioni, una chiave derivata a 256 bit, un salt casuale di 16 byte e un IV casuale di 12 byte. Memorizzate il payload crittografato dell'allegato come oggetto JSON, quindi codificate la stringa JSON in Base64:

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

Caricamento del file crittografato

Quando è incluso un allegato, la risposta di creazione del segreto contiene una destinazione di caricamento in data.attachment.upload:

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

Caricate il JSON crittografato codificato in Base64 come text/plain usando multipart/form-data all'upload.url restituito. Aggiungete tutte le coppie chiave/valore restituite in upload.metadata o upload.fields ai dati del modulo prima di aggiungere il file crittografato. Il campo del file crittografato deve chiamarsi file.

Per gli URL di caricamento Password.link, includi la stessa chiave API privata nell'intestazione Authorization: ApiKey <key>. Gli URL di caricamento diretto su storage, come gli URL S3 prefirmati, devono ricevere solo i campi del modulo restituiti e il campo file crittografato.

Visualizza il Segreto

Recupera il testo cifrato, la parte privata della password e altri dettagli di un segreto. Questo endpoint può essere utilizzato per creare una pagina personalizzata self-hosted per visualizzare il segreto che non carica script o altre risorse dal nostro servizio. Restituisce 200 OK in caso di successo.

Esempio di richiesta

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

Esempio di risposta

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

Conferma Secret

Invia la conferma del destinatario per un segreto creato con ack_required e restituisce gli stessi dati del segreto di View Secret quando la conferma è valida. Restituisce 200 OK in caso di successo.

Se è richiesta la conferma, GET /api/secrets/<id> restituisce 403 Forbidden con secret_status impostato su ack_required finché non viene utilizzato questo endpoint.

I payload di conferma non validi o incompleti restituiscono anch'essi 403 Forbidden. Non vengono restituiti come errori di validazione.

Parametri della richiesta

Esempio di richiesta

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

Elenco Segreti

Recupera un elenco di segreti. Non contiene i testi cifrati né le parti private delle password, solo ID, descrizioni e simili. Restituisce 200 OK in caso di successo.

Il numero massimo di risultati restituiti per ogni interrogazione è limitato a 50. Potete controllare l'offset con il parametro opzionale offset, ad esempio: /api/secrets?offset=50

Esempio di richiesta

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

Esempio di risposta

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

Aggiorna Secret

Aggiorna le impostazioni e i metadati supportati di un segreto esistente. Restituisce 204 No Content in caso di successo.

PATCH non sostituisce il contenuto crittografato del segreto, non invia nuovamente le email di consegna e non crea metadati di caricamento degli allegati. Usate Create Secret per il testo cifrato, le parti della password, la consegna del link e gli allegati.

I seguenti parametri possono essere aggiornati, con lo stesso significato di 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

Esempio di richiesta

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

Cancellare il segreto

Elimina un segreto. Restituisce 200 OK in caso di successo.

Esempio di richiesta

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

Esempio di risposta

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

Crea cartella di Secret

Crea una cartella di segreti. Restituisce 201 Created in caso di successo.

Parametri della richiesta

Esempio di risposta

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

Elenca cartelle di Secret

Recupera un elenco di cartelle di segreti. Restituisce 200 OK in caso di successo.

Esempio di risposta

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

Aggiorna cartella di Secret

Aggiorna il nome e la descrizione di una cartella di segreti. Accetta gli stessi parametri di Create Secret Folder e restituisce 204 No Content in caso di successo.

Cancellare la cartella segreta

Elimina una cartella di segreti. Restituisce 200 OK in caso di successo.

Creare una richiesta segreta

Crea una nuova richiesta di segreto. Restituisce 201 Created in caso di successo.

Parametri della richiesta

Esempio di richiesta

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

Esempio di risposta

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

Elenco Richieste segrete

Recupera un elenco di richieste di segreto. Restituisce 200 OK in caso di successo.

Il numero massimo di risultati restituiti per ogni interrogazione è limitato a 50. Potete controllare l'offset con il parametro opzionale offset, ad esempio: /api/secret_requests?offset=50

La risposta dell'elenco non include secret_allowed_emails né secret_allowed_ips.

Esempio di richiesta

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

Esempio di risposta

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

Eliminazione della richiesta segreta

Elimina una richiesta di segreto. Restituisce 200 OK in caso di successo.

Esempio di richiesta

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