API documentation

Overview

The base URL for all API endpoints is:

https://password.link/api

You can use the API to handle both encryption and decryption of the secret outside of our service, without needing to load any assets from us. It also allows you to use any kind of delivery method for the public password part (half of the password which is used to derive the encryption key for the secret from) and basically create any kind of custom configuration for viewing the secret.

For working end-to-end code, see the API examples.

Authentication

Every request must be authenticated with an API key, sent in the Authorization header:

Authorization: ApiKey public_key_abcd...

There are two kinds of API keys:

Both API keys contain the type of the key in the key itself so they can be easily distinguished.

Each endpoint below shows which key type it requires.

Errors

When a request fails, the response contains an error object:

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

The HTTP response status code also indicates the type of the error:

Encrypting secrets

Secrets are encrypted client-side before they are sent to the API. This section describes the password and ciphertext formats the service expects.

The password parts

The password which is used to encrypt the secret in AES must consist of two 18 character long strings. The actual encryption key will be the concatenation of these two strings ("private part" + "public part") and is derived from the password using PBKDF2.

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

The private part is sent to the API (Base64 encoded) and stored with the secret. The public part is never sent to the API, and is usually delivered in the link itself, so we can never decrypt the secret ourselves.

If you use the view secret page provided by us, you must also Base64 encode the public part. If you use a self-hosted view secret page, you can use the same method or create your own. Please see the API examples for reference implementations.

Ciphertext format

The ciphertext is a JSON object, encoded in Base64:

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

You must use the following settings for AES when encrypting the secret:

Legacy SJCL format (deprecated)

Decrypting secrets

The View Secret API returns the ciphertext exactly as it was stored. Secrets created in the web app use the Web Crypto format above. Secrets created by older API clients, the Chrome extension, or still-unopened links may use the legacy SJCL format.

A self-hosted view page must handle both. After Base64-decoding the ciphertext to JSON, check for a ct key: if it is present, decrypt with SJCL; otherwise decrypt with Web Crypto. See the View Secret example.

Create Secret

Creates an encrypted secret and returns its ID. The ciphertext must be created as described in Encrypting secrets. Returns 201 Created on success.

Request parameters

Example request

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

Example response

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

The link to the secret is formed by combining the hosted view page URL, the secret ID and the Base64 encoded public password part:

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

Attachments

Uploading an attachment is a two-step process: first create the secret with attachment metadata (see Create Secret), then encrypt and upload the encrypted attachment payload to the returned upload URL.

The secret contents and attachment contents are encrypted separately. Both use Web Crypto compatible AES-GCM data, Base64 encoded, but the payload fields are encoded differently: the secret payload stores Base64 encoded fields and an iter field, while the attachment payload stores raw binary string fields.

Encrypting the attachment

Before encryption, represent the file as a data URL:

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

The attachment encryption password is the raw private password part concatenated with the raw public password part (no Base64 encoding).

Encrypt that data URL string with AES-GCM using PBKDF2-SHA256, 10000 iterations, a 256-bit derived key, a 16-byte random salt and a 12-byte random IV. Store the encrypted attachment payload as a JSON object, then Base64 encode the JSON string:

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

Uploading the encrypted file

When an attachment is included, the create secret response contains an upload target in data.attachment.upload:

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

Upload the Base64 encoded encrypted JSON as text/plain using multipart/form-data to the returned upload.url. Add any returned upload.metadata or upload.fields key/value pairs to the form data before adding the encrypted file. The encrypted file field must be named file.

For Password.link upload URLs, include the same private API key in the Authorization: ApiKey <key> header. Direct storage upload URLs, such as pre-signed S3 URLs, should only receive the returned form fields and the encrypted file field.

View Secret

Fetches the ciphertext, private password part and other details of a secret. This endpoint can be used to create a custom self-hosted view secret page which does not load any scripts or other assets from our service. Returns 200 OK on success.

Example request

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

Example response

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

Acknowledge Secret

Submits recipient acknowledgement for a secret that was created with ack_required, and returns the same secret data as View Secret when the acknowledgement is valid. Returns 200 OK on success.

If acknowledgement is required, GET /api/secrets/<id> returns 403 Forbidden with secret_status set to ack_required until this endpoint is used.

Invalid or incomplete acknowledgement payloads also return 403 Forbidden. They are not returned as validation errors.

Request parameters

Example request

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

List Secrets

Fetches a list of secrets. Does not contain the ciphertexts or private password parts, only IDs, descriptions and the like. Returns 200 OK on success.

The maximum amount of returned results for each query is limited to 50. You can control the offset with the optional offset query parameter, for example: /api/secrets?offset=50

Example request

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

Example response

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

Update Secret

Updates supported settings and metadata for an existing secret. Returns 204 No Content on success.

PATCH does not replace the encrypted secret content, re-send delivery emails, or create attachment upload metadata. Use Create Secret for ciphertext, password parts, link delivery, and attachments.

The following parameters can be updated, with the same meaning as in 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

Example request

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

Delete Secret

Deletes a secret. Returns 200 OK on success.

Example request

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

Example response

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

Create Secret Folder

Creates a secret folder. Returns 201 Created on success.

Request parameters

Example response

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

List Secret Folders

Fetches a list of secret folders. Returns 200 OK on success.

Example response

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

Update Secret Folder

Updates the name and description of a secret folder. Accepts the same parameters as Create Secret Folder and returns 204 No Content on success.

Delete Secret Folder

Deletes a secret folder. Returns 200 OK on success.

Create Secret Request

Creates a new Secret Request. Returns 201 Created on success.

Request parameters

Example request

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

Example response

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

List Secret Requests

Fetches a list of Secret Requests. Returns 200 OK on success.

The maximum amount of returned results for each query is limited to 50. You can control the offset with the optional offset query parameter, for example: /api/secret_requests?offset=50

The list response does not include secret_allowed_emails or secret_allowed_ips.

Example request

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

Example response

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

Delete Secret Request

Deletes a Secret Request. Returns 200 OK on success.

Example request

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