# API e bibliotecas de cliente

> Crie, recupere e queime mensagens confidenciais a partir do seu próprio código. URLs de base regionais, autenticação, um início rápido com curl e as bibliotecas de cliente oficiais e da comunidade.

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](https://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.

```plaintext
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](/en/security/where-your-data-lives/) para saber o que cada região significa para os seus dados.

Em um [domínio personalizado](/pt-br/custom-domains/), a API fica no mesmo caminho no seu domínio, e os links que ela cria usam esse domínio:

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

Uma instância [auto-hospedada](/pt-br/self-hosting/) 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.

```bash
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](/en/share/your-receipt/).

## Início rápido

Crie uma mensagem confidencial que dura uma hora:

```bash
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:

```bash
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:

```bash
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](https://api.onetimesecret.com).

## Bibliotecas de cliente

[Bibliotecas de cliente](/pt-br/api/client-libraries/)O 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 API](https://api.onetimesecret.com)Todos 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](/en/security/where-your-data-lives/): escolher uma região e o que permanece dentro dela.
* [Domínios personalizados](/pt-br/custom-domains/): links confidenciais e acesso à API no seu próprio domínio.
* [Auto-hospedagem](/pt-br/self-hosting/): execute a API na sua própria infraestrutura.
* [Primeiros passos para desenvolvedores](/en/contribute/developer-on-ramp/): execute a aplicação localmente e contribua.