Documentação da API

Geral

Dispomos de uma API REST padrão para gerir segredos. Todas as solicitações e respostas usam o JSON formato.

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.

Exemplos de código

Consulte os nossos exemplos de API para saber como utilizar a API.

Autenticação

Utilizamos dois tipos de chaves API para autenticação:

  • Chaves públicas da API
  • Chaves privadas da API

As chaves de API públicas destinam-se à criação de uma página secreta de visualização auto-hospedada personalizada. Todas as outras acções da API requerem uma chave de API privada.

As chaves de API públicas podem ser utilizadas em scripts públicos. As chaves de API privadas devem ser sempre mantidas privadas.

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

A chave da API deve ser enviada no ficheiro Authorization: ApiKey <key> cabeçalho, como:

Authorization: ApiKey public_key_abc...

Erros

Se a consulta não for bem sucedida, a resposta terá um error objeto.

O objeto contém os seguintes campos:

  • mensagem: a mensagem de erro completa, por exemplo, "Ciphertext can\'t be blank" (o texto cifrado não pode estar em branco)
  • campo: o campo a que se refere o erro, por exemplo, "ciphertext" (texto cifrado)

O código de estado da resposta HTTP também indicará um erro, por exemplo:

  • 403 Forbidden: o pedido não foi permitido, por exemplo, devido a uma chave de API inválida
  • 404 Not Found: o segredo pedido não foi encontrado

Ver segredo

Tipo de pedido: GET

Caminho do pedido: https://password.link/api/secrets/<id>

Código de estado da consulta bem sucedida: 200 OK


Obtém o texto cifrado, a parte da palavra-passe privada e outros detalhes de um segredo. Requer o público Chave da API.

Esta consulta da API pode ser utilizada para criar uma página secreta de visualização auto-hospedada personalizada que não carrega quaisquer scripts ou outros activos do nosso serviço.

A obtenção bem sucedida de um segredo marca-o automaticamente como visualizado e, assim, elimina o texto cifrado e a parte da palavra-passe privada da nossa base de dados, tornando impossível visualizar novamente o segredo.

Parâmetros necessários
  • id: o id do segredo, por exemplo dT5g

Exemplo de consulta

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

Exemplo de resposta

{
        "data": {
          "id": "a identificação do segredo",
          "ciphertext": "o texto cifrado do segredo",
          "password_part_private": "a parte da palavra-passe privada do segredo",
          "message": "a mensagem para o segredo, se definido"
        },
        "metadata": null
      }

Exemplo de código

Consulte os nossos exemplos de API.

Criar segredo

Tipo de pedido: POST

Caminho do pedido: https://password.link/api/secrets

Código de estado da consulta bem sucedida: 201 Created

Esta chamada de API também permite adicionar um anexo de arquivo criptografado ao segredo.


Criar um segredo encriptado.

Para encriptar o segredo do lado do cliente antes de o enviar para a nossa API é necessário criar uma cadeia JSON de texto cifrado compatível com SJCL. Consulte o <a href=\"https://github.com/bitwiseshiftleft/sjcl\">Documentação SJCL</a> para obter o formato correto da cadeia JSON e veja o nosso <a href=\"/p/docs/api/examples\">Exemplos de API</a> para exemplos de como criar o texto cifrado.

Criar a palavra-passe para encriptar o segredo

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 pelo SJCL utilizando o PBKDF2.

Exemplo de criação das partes privada e pública da palavra-passe:

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

A parte privada tem de ser codificada em Base64 antes de ser enviada para a nossa API. Se utilizar a página de segredo de visualização fornecida por nós, deve também codificar a parte pública em Base64. Se utilizar uma página de segredo de visualização auto-hospedada, pode utilizar o mesmo método ou criar a sua própria página. Consulte o nosso <a href=\"/p/docs/api/examples\">Exemplos de API</a> para obter implementações de referência.

Definições necessárias do SJCL AES

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

  • Modo: AES-GCM (definição SJCL: "mode:gcm")
  • Tamanho da chave: 256 bits (definição SJCL: "ks:256")
  • Função de derivação de chaves: PBKDF2 (predefinição SJCL)
  • Iterações PBKDF2: 10000 (Definição SJCL: "iter:10000")

Carga útil do pedido

{
        "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âmetros do pedido

  • ciphertext: Uma cadeia JSON de texto cifrado compatível com SJCL do segredo, codificada em Base64.
  • password_part_private: a parte da palavra-passe privada que foi utilizada para encriptar o segredo, em Base64.
  • password_part_public (facultativo): a parte pública da palavra-passe, em Base64. Necessário apenas ao usar email_to para que a API possa enviar por e-mail a ligação do Secret alojado.
  • description (facultativo): uma descrição para o segredo. Não pode ser visto quando se está a ver o segredo.
  • message (facultativo): uma mensagem para o segredo. Será mostrada ao longo do segredo.
  • expiration (facultativo): um tempo de expiração para o segredo, em horas. Valores possíveis: 1-500.
  • view_button (facultativo): mostrar um botão de ver segredo em vez de mostrar o segredo imediatamente após abrir a ligação. Para ativar esta funcionalidade, defina isto para true.
  • captcha (facultativo): mostrar um CAPTCHA simples antes de mostrar o segredo, principalmente para bloquear scanners automáticos. Para ativar esta funcionalidade, defina isto para true.
  • password (facultativo): uma palavra-passe para o segredo.
  • max_views (facultativo): o número de vezes que o segredo pode ser visualizado. Valores possíveis: 1-100.
  • email_to (facultativo): destinatários de e-mail separados por vírgulas que devem receber a ligação do Secret criado. Requer password_part_public.
  • otp_email_recipient (facultativo): endereço de e-mail que recebe uma palavra-passe de utilização única. Quando definido, o destinatário deve introduzir o código enviado por e-mail antes de poder ver o Secret.
  • otp_recipient (facultativo): aceite como alias para otp_email_recipient. Prefira otp_email_recipient para novas integrações.
  • otp_sms_recipient (facultativo): número de telefone que recebe uma palavra-passe de utilização única por SMS, em formato internacional começando por + e sem espaços.
  • allowed_ips (facultativo): endereços IP ou intervalos CIDR separados por vírgulas autorizados a ver o Secret.
  • allowed_locations (facultativo): array de códigos de país ISO 3166-1 alfa-2 autorizados a ver o Secret.
  • available_after (facultativo): data e hora antes das quais o Secret não pode ser visualizado.
  • secret_folder_id (facultativo): ID de uma pasta de Secrets existente pertencente ao utilizador da chave API.
  • reply_enabled (facultativo): ativar uma resposta de utilização única do destinatário depois de o Secret ter sido visualizado.
  • ack_required (facultativo): exigir confirmação do destinatário antes de o Secret poder ser visualizado.
  • ack_mode (facultativo): modo de confirmação. Use checkbox ou phrase.
  • ack_phrase (necessário quando ack_required é verdadeiro e ack_mode é phrase): frase que o destinatário deve escrever.
  • ack_disclosure_text (facultativo): texto de divulgação mostrado ao destinatário, até 500 caracteres.
  • ack_collect_name (facultativo): recolher o nome do destinatário com a confirmação.
  • ack_name_required (facultativo): exigir o nome do destinatário. Isto também ativa ack_collect_name.
  • ack_collect_org (facultativo): recolher a organização do destinatário com a confirmação.
  • attachment (facultativo): metadados de um anexo de arquivo criptografado. Requer um plano ativo. O arquivo criptografado é enviado separadamente depois que o segredo é criado.
  • attachment.file_name (obrigatório quando um anexo é fornecido): o nome original do arquivo mostrado ao destinatário.
  • attachment.file_type (obrigatório quando um anexo é fornecido): o tipo MIME original, por exemplo text/plain ou application/pdf.
  • attachment.file_size (obrigatório quando um anexo é fornecido): o tamanho original não criptografado do arquivo em bytes.

As Definições de Secrets da Equipa podem desativar, exigir ou impor predefinições para opções de Secret suportadas. A API aplica essas regras da equipa ao criar um Secret.

Enviando um anexo

Enviar um anexo é um processo em duas etapas: primeiro crie o segredo com os metadados do anexo, depois criptografe e envie a carga útil criptografada do anexo para a URL de upload retornada.

O conteúdo do segredo e o conteúdo do anexo são criptografados separadamente. O texto cifrado do segredo são dados AES-GCM compatíveis com SJCL, codificados em Base64. O anexo é criptografado com dados AES-GCM compatíveis com Web Crypto e depois codificado em Base64.

A senha de criptografia do anexo é a parte privada bruta da senha concatenada com a parte pública bruta da senha: <raw private password part> + <raw public password part>.

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

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

URLs de upload hospedadas no Password.link incluem um objeto fields vazio. URLs de upload direto para armazenamento, como URLs S3 pré-assinadas, retornam os campos de assinatura em metadata.

Antes da criptografia, represente o arquivo como uma URL de dados: data:<mime-type>;base64,<base64 file bytes>.

Criptografe essa string de URL de dados 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. Armazene a carga criptografada do anexo como um objeto JSON contendo cipher, iv e salt, e depois codifique a string JSON em Base64.

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

Envie o JSON criptografado codificado em Base64 como text/plain usando multipart/form-data para a URL retornada upload.url. Adicione todos os upload.metadata ou upload.fields pares de chave/valor retornados aos dados do formulário antes de adicionar o arquivo criptografado. O campo do arquivo criptografado deve ser chamado 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.

A resposta da API de criação de segredo retorna um destino de upload de anexo para o único parâmetro attachment . Os limites de tamanho de anexos dependem da cota da conta ou da equipe, e o upload criptografado é maior que o arquivo original porque o arquivo é convertido para Base64 e criptografado.

Exemplo de código

Consulte os nossos exemplos de API.

Confirmar Secret

Tipo de pedido: POST

Caminho do pedido: https://password.link/api/secrets/<id>/acknowledge

Código de estado da consulta bem sucedida: 200 OK


Enviar a confirmação do destinatário para um Secret criado com ack_required. Requer a público chave API e devolve os mesmos dados do Secret que Ver Secret quando a confirmação é válida.

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

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

  • ack_confirmed: definido como true para confirmação por caixa de seleção.
  • ack_phrase: necessário para confirmação por frase, e deve corresponder à frase configurada para o Secret.
  • ack_signer_name: nome do destinatário, necessário quando a recolha de nome está ativada e marcada como obrigatória.
  • ack_signer_org: organização do destinatário, guardada quando a recolha de organização está ativada.

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

Exemplo de resposta

{
        "data": {
          "id": "a identificação do segredo",
          "ciphertext": "o texto cifrado do segredo",
          "password_part_private": "a parte da palavra-passe privada do segredo",
          "message": "a mensagem para o segredo, se definido"
        },
        "metadata": null
      }

Segredos da lista

Tipo de pedido: GET

Caminho do pedido: https://password.link/api/secrets

Código de estado da consulta bem sucedida: 200 OK


Obtém uma lista de segredos. Não contém as partes da palavra-passe privada dos textos cifrados, apenas IDs, descrições e afins.

Limite e desvio

A quantidade máxima de segredos devolvidos para cada consulta é limitada a 50. Pode controlar o offset com o parâmetro opcional offset parâmetro de consulta.

Por exemplo, para saltar os primeiros 50 registos, utilize uma consulta como: .../api/secrets?offset=50

Exemplo de consulta

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

Exemplo de resposta

{
        "data": [
          {
            "id": a identificação do segredo,
            "created_at": quando o segredo foi criado,
            "message": a mensagem para o segredo,
            "description": a descrição do segredo,
            "view_button": o botão ver segredo está ativado,
            "captcha": o CAPTCHA está ativado,
            "password": o segredo tem uma palavra-passe,
            "expiration": tempo de expiração em horas,
            "expired": o segredo expirou,
            "view_times": quantas vezes o segredo foi visto,
            "max_views": o número máximo de vezes que o segredo pode ser visualizado,
            "secret_folder_id": "5e976e6e-d205-4f58-8df9-5ac0048bc702",
            "views": [
              {
                "viewed_at": um registo de data e hora em que o segredo foi visualizado,
                "viewed_by_ip": Endereço IP do visualizador,
                "viewed_by_user_agent": agente do utilizador do visualizador
              }
            ]
          }
        ],
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Atualizar Secret

Tipo de pedido: PATCH

Caminho do pedido: https://password.link/api/secrets/<id>

Código de estado da consulta bem sucedida: 204 No Content


Atualizar definições e metadados suportados para um Secret existente. Requer a privada chave API. PATCH não substitui o conteúdo encriptado do Secret, não reenvia e-mails de entrega nem cria metadados de carregamento de anexos. Use Criar Secret para ciphertext, partes da palavra-passe, entrega de ligação e anexos.

Parâmetros do pedido

  • description, message, expiration, max_views, view_button, captcha, password: mesmo significado que em Criar Secret.
  • otp_email_recipient, otp_recipient, otp_sms_recipient: mesmo significado que em Criar Secret.
  • allowed_ips, allowed_locations, available_after: mesmo significado que em Criar Secret.
  • secret_folder_id, reply_enabled: mesmo significado que em Criar Secret.
  • ack_required, ack_mode, ack_phrase, ack_disclosure_text, ack_collect_name, ack_name_required, ack_collect_org: mesmo significado que em Criar Secret.

ciphertext, password_part_private, password_part_public, email_to e os metadados de anexos são apenas para criação. São ignorados pelo PATCH.

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

Eliminar segredo

Tipo de pedido: DELETE

Caminho do pedido: https://password.link/api/secrets/<id>

Código de estado da consulta bem sucedida: 200 OK


Eliminar um segredo.

Exemplo de consulta

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

Exemplo de resposta

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

Pastas secretas

Os endpoints da API de pastas de Secrets requerem a privada Chave da API.

Criar pasta de Secrets

Tipo de pedido: POST

Caminho do pedido: https://password.link/api/secret_folders

Código de estado da consulta bem sucedida: 201 Created

  • name: nome da pasta.
  • description (facultativo): descrição da pasta.

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

Tipo de pedido: GET

Caminho do pedido: https://password.link/api/secret_folders

Código de estado da consulta bem sucedida: 200 OK

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

Tipo de pedido: PATCH

Caminho do pedido: https://password.link/api/secret_folders/<id>

Código de estado da consulta bem sucedida: 204 No Content

Eliminar a pasta secreta

Tipo de pedido: DELETE

Caminho do pedido: https://password.link/api/secret_folders/<id>

Código de estado da consulta bem sucedida: 200 OK

Criar pedido secreto

Tipo de pedido: POST

Caminho do pedido: https://password.link/api/secret_requests

Código de estado da consulta bem sucedida: 201 Created


Criar um novo pedido secreto.

Parâmetros do pedido

  • description: descrição do pedido secreto.
  • message: mensagem para o visualizador do Pedido Secreto.
  • expiration: tempo de expiração do Pedido Secreto, em horas.
  • limit: limite de utilização do pedido secreto.
  • send_request_to_email: envia a ligação do Pedido Secreto criada para o endereço de correio eletrónico indicado.
  • send_request_to_sms: enviar a ligação do Secret Request criado para o número de telefone indicado.
  • send_to_email: envia a ligação secreta criada utilizando o Pedido de Segredo para o endereço de correio eletrónico indicado.
  • secret_description: descrição para o Segredo criado utilizando o Pedido de Segredo.
  • secret_message: mensagem para o Segredo criado utilizando o Pedido de Segredo.
  • secret_expiration: tempo de expiração para o Segredo criado utilizando o Pedido de Segredo, em horas.
  • secret_password: palavra-passe para o Secret criado usando o Secret Request.
  • secret_max_views: limite de visualização para o Segredo criado utilizando o Pedido de Segredo.
  • template_id: ID do modelo de pedido a usar.
  • secret_allowed_emails: endereços de e-mail ou domínios separados por vírgulas autorizados a abrir Secrets criados com este Secret Request.
  • secret_allowed_ips: endereços IP ou intervalos CIDR separados por vírgulas autorizados a abrir Secrets criados com este Secret Request.

Exemplo de consulta

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

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

Tipo de pedido: GET

Caminho do pedido: https://password.link/api/secret_requests

Código de estado da consulta bem sucedida: 200 OK


Limite e desvio

A quantidade máxima de resultados devolvidos para cada consulta é limitada a 50. Pode controlar o offset com o parâmetro de consulta opcional offset.

Por exemplo, para saltar os primeiros 50 registos, utilize uma consulta como: .../api/secret_requests?offset=50

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

Exemplo de consulta

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

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

Pedido de eliminação de segredo

Tipo de pedido: DELETE

Caminho do pedido: https://password.link/api/secret_requests/<id>

Código de estado da consulta bem sucedida: 200 OK


Eliminar um pedido secreto.

Exemplo de consulta

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

Exemplo de resposta

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