API y bibliotecas de cliente

Todo lo que la aplicación web hace con un secreto puede hacerse a través de HTTPS con JSON. El patrón habitual es un script o una canalización que crea un secreto y entrega el enlace a una persona, de modo que la credencial nunca queda en un registro, un ticket o un historial de chat.

La referencia completa de puntos de conexión, con los esquemas de solicitud y respuesta y una consola de pruebas, está en api.onetimesecret.com. Esta página cubre lo que necesita antes de abrirla.

URL base

Las solicitudes van a la región que aloja su cuenta. Cada región es un despliegue independiente y nada se replica entre ellas.

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`

El host onetimesecret.com sin prefijo sigue respondiendo a las solicitudes de API y las enruta a una región activa, pero fije una región de forma explícita para que su integración siga funcionando si ese mecanismo de respaldo se retira. Consulte Dónde residen sus datos para saber qué implica cada región para sus datos.

En un dominio personalizado, la API está en la misma ruta de su dominio, y los enlaces que crea la API usan ese dominio:

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

Una instancia autoalojada expone la misma API en el host en el que la ejecute.

Autenticación

Use autenticación HTTP Basic. El nombre de usuario es el correo electrónico de su cuenta; la contraseña es el token de API de la configuración de su cuenta.

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

Crear y revelar secretos también funciona sin autenticación, con los límites de un usuario anónimo: duración máxima más corta, tamaño de secreto más pequeño y sin lista de recibos. Las solicitudes autenticadas obtienen los límites de su plan y aparecen en sus recibos.

Inicio rápido

Cree un secreto que dure una 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

La respuesta contiene dos registros. record.secret.identifier es la clave que usted comparte, como https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier es suya: muestra si el secreto ha sido visto y le permite destruirlo de forma anticipada. Nunca envíe la clave del recibo al destinatario.

Añada "passphrase": "..." al objeto secret para exigir una frase de contraseña al verlo. La frase de contraseña es una comprobación de acceso, no la clave de cifrado: el servicio solo almacena un hash unidireccional de ella y la comprueba antes de descifrar el valor. Una frase de contraseña perdida no se puede recuperar, por lo que el secreto ya no se puede revelar ni destruir; se elimina cuando expira.

Revele un secreto, lo que lo consume:

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

Destruya un secreto antes de que alguien lo vea, usando la clave del recibo:

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

Versiones de la API

v2 es la API pública actual: JSON de entrada y de salida, recibos, puntos de conexión de estado y de destrucción. Use esta versión para sus integraciones.
v1 es la API original codificada como formulario (POST /api/v1/share). Sigue funcionando, y la mayoría de las bibliotecas de la comunidad la usan, pero las integraciones nuevas deberían usar v2.

Ambas están documentadas en api.onetimesecret.com.

Bibliotecas de cliente

Bibliotecas de clienteEl SDK oficial y las bibliotecas de la comunidad, con notas sobre cuáles admiten la API v2, las regiones y los dominios personalizados.

Referencia completa de la APITodos los puntos de conexión de v1 y v2, los esquemas de solicitud y respuesta, y una consola para probar llamadas con su cuenta.

Contenido relacionado

Dónde residen sus datos: elegir una región y qué permanece dentro de ella.
Dominios personalizados: enlaces secretos y acceso a la API en su propio dominio.
Autoalojamiento: ejecute la API en su propia infraestructura.
Guía de inicio para desarrolladores: ejecute la aplicación en local y contribuya.