API e bibliotecas de cliente

Tudo o que o aplicativo web faz com uma mensagem confidencial pode ser feito por HTTPS com JSON. O padrão comum é um script ou pipeline que cria uma mensagem confidencial e entrega o link a uma pessoa, para que a credencial nunca fique em um log, em um chamado ou em um histórico de chat.

A referência completa de endpoints, com esquemas de requisição e resposta e um console para testes, fica em api.onetimesecret.com. Esta página cobre o que você precisa saber antes de abri-la.

URL de base

As requisições vão para a região que mantém a sua conta. Cada região é uma implantação separada, e nada é replicado entre elas.

https://REGION.onetimesecret.com/api/v2

`REGION`	Host
`ca`	`ca.onetimesecret.com`
`eu`	`eu.onetimesecret.com`
`nz`	`nz.onetimesecret.com`
`uk`	`uk.onetimesecret.com`
`us`	`us.onetimesecret.com`

O host simples onetimesecret.com ainda responde a requisições de API e as encaminha para uma região ativa, mas fixe uma região explicitamente para que a sua integração continue funcionando caso esse fallback seja desativado. Consulte Onde seus dados ficam para saber o que cada região significa para os seus dados.

Em um domínio personalizado, a API fica no mesmo caminho no seu domínio, e os links que ela cria usam esse domínio:

https://secrets.example.com/api/v2

Uma instância auto-hospedada expõe a mesma API em qualquer host em que você a execute.

Autenticação

Use autenticação HTTP Basic. O nome de usuário é o e-mail da sua conta; a senha é o token de API das configurações da sua conta.

curl -u 'you@example.com:APITOKEN' https://eu.onetimesecret.com/api/v2/status

Criar e revelar mensagens confidenciais também funciona sem autenticação, com os limites de um usuário anônimo: duração máxima mais curta, tamanho menor da mensagem confidencial e nenhuma lista de comprovantes. As requisições autenticadas recebem os limites do seu plano e aparecem nos seus comprovantes.

Início rápido

Crie uma mensagem confidencial que dura uma hora:

curl -u 'you@example.com:APITOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"secret": {"secret": "the password is hunter2", "ttl": 3600}}' \
  https://eu.onetimesecret.com/api/v2/secret/conceal

A resposta contém dois registros. record.secret.identifier é a chave que você compartilha, na forma https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier é sua: ela mostra se a mensagem confidencial foi visualizada e permite queimá-la antecipadamente. Nunca envie a chave do comprovante ao destinatário.

Adicione "passphrase": "..." ao objeto secret para exigir uma frase secreta na visualização. A frase secreta é uma verificação de acesso, não a chave de criptografia: o serviço armazena apenas um hash unidirecional dela e a verifica antes de descriptografar o valor. Uma frase secreta perdida não pode ser recuperada, então a mensagem confidencial não pode mais ser revelada nem queimada; ela é excluída quando expira.

Revele uma mensagem confidencial, o que a consome:

curl -X POST -H 'Content-Type: application/json' -d '{}' \
  https://eu.onetimesecret.com/api/v2/secret/IDENTIFIER/reveal

Queime uma mensagem confidencial antes que alguém a visualize, usando a chave do comprovante:

curl -u 'you@example.com:APITOKEN' -X POST \
  https://eu.onetimesecret.com/api/v2/receipt/RECEIPT_IDENTIFIER/burn

Versões da API

v2 é a API pública atual: JSON na entrada e na saída, comprovantes, endpoints de status e de queima. Use esta como base.
v1 é a API original codificada como formulário (POST /api/v1/share). Ela ainda funciona, e a maioria das bibliotecas da comunidade a usa, mas novas integrações devem usar a v2.

Ambas estão documentadas em api.onetimesecret.com.

Bibliotecas de cliente

Bibliotecas de clienteO SDK oficial e as bibliotecas da comunidade, com notas sobre quais oferecem suporte à API v2, a regiões e a domínios personalizados.

Referência completa da APITodos os endpoints das versões v1 e v2, esquemas de requisição e resposta e um console para testar chamadas com a sua conta.

Relacionados

Onde seus dados ficam: escolher uma região e o que permanece dentro dela.
Domínios personalizados: links confidenciais e acesso à API no seu próprio domínio.
Auto-hospedagem: execute a API na sua própria infraestrutura.
Primeiros passos para desenvolvedores: execute a aplicação localmente e contribua.