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": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

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 à API também permite adicionar um anexo ao segredo. Para mais informações, contacte-nos.

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",
        "description": "description",
        "message": "message",
        "expiration": "expiration",
        "view_button": "view_button",
        "captcha": "captcha",
        "password": "password",
        "max_views": "max_views"
      }

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.
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: 0-350.
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.

Exemplo de código

Consulte os nossos exemplos de API.

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

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

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_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 Segredo criado utilizando o Pedido de Segredo, em horas.
secret_max_views: limite de visualização para o Segredo criado utilizando o Pedido de Segredo.

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

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