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

• Chaves de API públicas
• 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 privadas da API devem ser sempre mantidas privadas.

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

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

Authorization: ApiKey public_key_abc...

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

O objeto contém os seguintes campos:

• message: a mensagem de erro completa, por exemplo, "Ciphertext can't be blank" (o texto cifrado não pode estar em branco)
• campo: o campo sobre o qual incide o erro, por exemplo, "ciphertext"

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 Não encontrado: o segredo solicitado não foi encontrado

Tipo de pedido: GET

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

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

Obter o texto cifrado, a parte da palavra-passe privada e outros detalhes de um segredo. Requer a chave pública da API.

Esta consulta da API pode ser utilizada para criar uma página personalizada de visualização de segredos auto-hospedada 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, por isso, elimina o texto cifrado e a parte da palavra-passe privada da nossa base de dados, impossibilitando a visualização do segredo novamente.

Parâmetros necessários

• id: o id do segredo, por exemplo dT5g

Exemplo de consulta

curl -H "Autorização: ApiKey public_key_abcd" https://password.link/api/secrets/dT5g

Exemplo de resposta

{
"data": {
  "id":"o ID do segredo",
  "ciphertext":"o texto cifradodo segredo",
  "password_part_private":"a parte da palavra-passe privada do segredo",
  "message":"the message for the secret, if set" (a mensagem para o segredo, se definido)
},
"metadata": {
  "secrets_total": 1,
  "secrets_usage": 1,
  "permissão de segredos": 1
}
}

Exemplo de código

Consulte os nossos exemplos de API.

Tipo de pedido: POST

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

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

Esta chamada à API também permite adicionar um anexo ao segredo. Contacte-nos para obter mais informações.

Criar um segredo encriptado.

A encriptação do segredo no lado do cliente antes de o enviar para a nossa API requer a criação de uma cadeia JSON de texto cifrado compatível com SJCL. Consulte a documentação SJCL para obter o formato correto da cadeia JSON e consulte os nossos exemplos de API para obter exemplos sobre como criar o texto cifrado.

Criar a palavra-passe para encriptar o segredo

A palavra-passe 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:

Palavra-passe: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
=> Parte privada: fkgjbnvlakwiejgutn
=> Parte pública: FIGKEOTIRUBNAKQJRL

A parte privada precisa de ser codificada em Base64 antes de ser enviada para a nossa API. Se utilizar a página view secret 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 o seu próprio. Consulte os nossos exemplos de API para obter implementações de referência.

Definições AES do SJCL necessárias

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

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

Carga útil do pedido

{
"ciphertext":"ciphertext",
"password_part_private":"password_part_private",
"description":"description" (descrição),
"message" (mensagem):"message" (mensagem),
"expiração":"expiração",
"botão de visualização":"botão de visualização",
"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, codificado em Base64.
• password_part_private: a parte da palavra-passe privada que foi utilizada para encriptar o segredo, no formato Base64.
• description (opcional): uma descrição para o segredo. Não pode ser vista ao visualizar o segredo.
• message (opcional): uma mensagem para o segredo. Será mostrada ao longo do segredo.
• expiração (opcional): um tempo de expiração para o segredo, em horas. Valores possíveis: 0-350.
• view_button (opcional): mostra um botão de visualização do segredo em vez de mostrar o segredo imediatamente após a abertura da ligação. Para ativar esta funcionalidade, defina este valor como verdadeiro.
• captcha (opcional): mostra um CAPTCHA simples antes de mostrar o segredo, principalmente para bloquear scanners automáticos. Para ativar esta funcionalidade, defina esta opção como verdadeira.
• password (opcional): uma password para o segredo.
• max_views (opcional): o número de vezes que o segredo pode ser visto. Valores possíveis: 1-100.

Exemplo de código

Consulte os nossos exemplos de API.

Tipo de pedido: GET

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

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

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

Limite e desvio

A quantidade máxima de segredos devolvidos para cada consulta está 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/secrets?offset=50

Exemplo de consulta

curl -H "Autorização: ApiKey private_key_abcd" https://password.link/api/secrets

Exemplo de resposta

{
"data": [
  {
    "id": a ID do segredo,
    "created_at": quando o segredo foi criado,
    "message": a mensagem para o segredo,
    "description" (descrição): a descrição do segredo,
    "view_button": o botão de visualização do segredo está ativado,
    "captcha": o CAPTCHA está ativado,
    "password": o segredo tem uma palavra-passe,
    "expiration": tempo de expiração em horas,
    "expired" (expirado): o segredo expirou,
    "view_times": quantas vezes o segredo foi visualizado,
    "max_views": o número máximo de vezes que o segredo pode ser visualizado,
    "views": [
      {
        "viewed_at": um registo de data e hora de quando o segredo foi visualizado,
        "viewed_by_ip": Endereço IP do visualizador,
        "viewed_by_user_agent": agente do utilizador do visualizador
      }
    ]
  }
],
"metadata": {
  "segredos_total": 1,
  "segredos_utilização": 1,
  "permissão de segredos": 1
}
}

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 "Autorização: ApiKey private_key_abcd" \
  -X DELETE https://password.link/api/secrets/dT5g

Exemplo de resposta

{
"data": nulo,
"metadata": {
  "segredos_total": 1,
  "segredos_utilização": 1,
  "permissão de segredos": 1
}
}

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

Tipo de pedido: GET

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

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

Lista Pedidos secretos.

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

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