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