Documentação da API

Visão geral

O URL base para todos os endpoints da API é:

https://password.link/api

Pode utilizar a API para tratar a encriptação e a desencriptação do segredo fora do nosso serviço, sem precisar de carregar quaisquer activos nossos. Também lhe permite utilizar qualquer tipo de método de entrega para a parte da palavra-passe pública (metade da palavra-passe que é utilizada para derivar a chave de encriptação do segredo) e, basicamente, criar qualquer tipo de configuração personalizada para visualizar o segredo.

Para código completo e funcional, consulte os Exemplos de API.

Autenticação

Cada pedido deve ser autenticado com uma chave de API, enviada no cabeçalho Authorization:

Authorization: ApiKey public_key_abcd...

Existem dois tipos de chaves de API:

Ambas as chaves API contêm o tipo da chave na própria chave para que possam ser facilmente distinguidas.

Cada endpoint abaixo mostra o tipo de chave que requer.

Erros

Quando um pedido falha, a resposta contém um objeto de erro:

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

O código de estado HTTP da resposta também indica o tipo de erro:

Encriptação de segredos

Os segredos são encriptados no lado do cliente antes de serem enviados para a API. Esta secção descreve os formatos de palavra-passe e de texto cifrado que o serviço espera.

As partes da palavra-passe

A palavra-passe que é utilizada para encriptar o segredo no AES deve consistir em duas cadeias de 18 caracteres. A chave de encriptação real será a concatenação destas duas cadeias ("parte privada" + "parte pública") e é derivada da palavra-passe utilizando o PBKDF2.

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

A parte privada é enviada para a API (codificada em Base64) e armazenada com o segredo. A parte pública nunca é enviada para a API e normalmente é entregue no próprio link, pelo que nós nunca podemos desencriptar o segredo.

Se utilizar a página de visualização do segredo fornecida por nós, também deve codificar a parte pública em Base64. Se utilizar uma página de visualização autoalojada, pode usar o mesmo método ou criar o seu próprio. Consulte os Exemplos de API para implementações de referência.

Formato do texto cifrado

O texto cifrado é um objeto JSON, codificado em Base64:

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

Deve utilizar as seguintes definições para o AES ao encriptar o segredo:

Formato SJCL legado (obsoleto)

Desencriptação de segredos

A API Ver segredo devolve o texto cifrado exatamente como foi armazenado. Os segredos criados na aplicação web utilizam o formato Web Crypto descrito acima. Os segredos criados por clientes da API mais antigos, pela extensão do Chrome ou por ligações ainda não abertas podem utilizar o formato SJCL legado.

Uma página de visualização autoalojada tem de suportar ambos os formatos. Depois de descodificar o texto cifrado de Base64 para JSON, verifique se existe uma chave ct: se estiver presente, desencripte com SJCL; caso contrário, desencripte com Web Crypto. Consulte o exemplo Ver segredo.

Criar segredo

Cria um segredo encriptado e devolve o seu ID. O texto cifrado deve ser criado conforme descrito em Encriptação de segredos. Devolve 201 Created em caso de sucesso.

Parâmetros do pedido

Exemplo de pedido

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

Exemplo de resposta

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

O link para o segredo é formado combinando o URL da página de visualização alojada, o ID do segredo e a parte pública da palavra-passe codificada em Base64:

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

Anexos

O carregamento de um anexo é um processo de dois passos: primeiro crie o segredo com os metadados do anexo (consulte Criar segredo), depois encripte e carregue o payload encriptado do anexo para o URL de carregamento devolvido.

O conteúdo do segredo e o conteúdo do anexo são criptografados separadamente. Ambos utilizam dados AES-GCM compatíveis com Web Crypto, codificados em Base64, mas os campos do payload são codificados de forma diferente: o payload do segredo contém campos codificados em Base64 e um campo iter, enquanto o payload do anexo contém campos de cadeias binárias em bruto.

Encriptação do anexo

Antes da criptografia, represente o arquivo como uma URL de dados:

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

A palavra-passe de encriptação do anexo é a parte privada em bruto da palavra-passe concatenada com a parte pública em bruto (sem codificação Base64).

Encripte essa cadeia data URL com AES-GCM usando PBKDF2-SHA256, 10000 iterações, uma chave derivada de 256 bits, um salt aleatório de 16 bytes e um IV aleatório de 12 bytes. Guarde o payload encriptado do anexo como um objeto JSON e depois codifique a cadeia JSON em Base64:

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

Carregamento do ficheiro encriptado

Quando é incluído um anexo, a resposta de criação do segredo contém um destino de carregamento em data.attachment.upload:

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

Carregue o JSON encriptado codificado em Base64 como text/plain usando multipart/form-data para o upload.url devolvido. Adicione todos os pares chave/valor devolvidos em upload.metadata ou upload.fields aos dados do formulário antes de adicionar o ficheiro encriptado. O campo do ficheiro encriptado deve chamar-se file.

Para URLs de upload da Password.link, inclua a mesma chave de API privada no cabeçalho Authorization: ApiKey <key>. URLs de upload direto para armazenamento, como URLs S3 pré-assinadas, devem receber apenas os campos de formulário retornados e o campo file criptografado.

Ver segredo

Obtém o texto cifrado, a parte privada da palavra-passe e outros detalhes de um segredo. Este endpoint pode ser utilizado para criar uma página personalizada e autoalojada para ver o segredo que não carrega scripts nem outros recursos do nosso serviço. Devolve 200 OK em caso de sucesso.

Exemplo de pedido

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

Exemplo 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 a confirmação do destinatário para um segredo criado com ack_required e devolve os mesmos dados do segredo que View Secret quando a confirmação é válida. Devolve 200 OK em caso de sucesso.

Se for necessária confirmação, GET /api/secrets/<id> devolve 403 Forbidden com secret_status definido como ack_required até que este endpoint seja utilizado.

Os payloads de confirmação inválidos ou incompletos também devolvem 403 Forbidden. Não são devolvidos como erros de validação.

Parâmetros do pedido

Exemplo de pedido

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

Segredos da lista

Obtém uma lista de segredos. Não contém os textos cifrados nem as partes privadas das palavras-passe, apenas IDs, descrições e semelhantes. Devolve 200 OK em caso de sucesso.

A quantidade máxima de resultados devolvidos por cada consulta está limitada a 50. Pode controlar o offset com o parâmetro de consulta opcional offset, por exemplo: /api/secrets?offset=50

Exemplo de pedido

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

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

Atualizar Secret

Atualiza as definições e os metadados suportados de um segredo existente. Devolve 204 No Content em caso de sucesso.

PATCH não substitui o conteúdo encriptado do segredo, não reenvia emails de entrega nem cria metadados de carregamento de anexos. Use Create Secret para o texto cifrado, as partes da palavra-passe, a entrega do link e os anexos.

Os seguintes parâmetros podem ser atualizados, com o mesmo significado que em 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

Exemplo de pedido

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

Eliminar segredo

Elimina um segredo. Devolve 200 OK em caso de sucesso.

Exemplo de pedido

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

Exemplo de resposta

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

Criar pasta de Secrets

Cria uma pasta de segredos. Devolve 201 Created em caso de sucesso.

Parâmetros do pedido

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

Listar pastas de Secrets

Obtém uma lista de pastas de segredos. Devolve 200 OK em caso de sucesso.

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

Atualizar pasta de Secrets

Atualiza o nome e a descrição de uma pasta de segredos. Aceita os mesmos parâmetros que Create Secret Folder e devolve 204 No Content em caso de sucesso.

Eliminar a pasta secreta

Elimina uma pasta de segredos. Devolve 200 OK em caso de sucesso.

Criar pedido secreto

Cria um novo pedido de segredo. Devolve 201 Created em caso de sucesso.

Parâmetros do pedido

Exemplo de pedido

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

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

Lista Pedidos secretos

Obtém uma lista de pedidos de segredo. Devolve 200 OK em caso de sucesso.

A quantidade máxima de resultados devolvidos por cada consulta está limitada a 50. Pode controlar o offset com o parâmetro de consulta opcional offset, por exemplo: /api/secret_requests?offset=50

A resposta da lista não inclui secret_allowed_emails nem secret_allowed_ips.

Exemplo de pedido

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

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

Pedido de eliminação de segredo

Elimina um pedido de segredo. Devolve 200 OK em caso de sucesso.

Exemplo de pedido

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