# API y bibliotecas de cliente

> Cree, recupere y destruya secretos desde su propio código. URL base regionales, autenticación, un inicio rápido con curl y las bibliotecas de cliente oficiales y de la comunidad.

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

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

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](/en/security/where-your-data-lives/) para saber qué implica cada región para sus datos.

En un [dominio personalizado](/es/custom-domains/), la API está en la misma ruta de su dominio, y los enlaces que crea la API usan ese dominio:

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

Una instancia [autoalojada](/es/self-hosting/) 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.

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

## Inicio rápido

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

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:

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

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

## Bibliotecas de cliente

[Bibliotecas de cliente](/es/api/client-libraries/)El 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 API](https://api.onetimesecret.com)Todos 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](/en/security/where-your-data-lives/): elegir una región y qué permanece dentro de ella.
* [Dominios personalizados](/es/custom-domains/): enlaces secretos y acceso a la API en su propio dominio.
* [Autoalojamiento](/es/self-hosting/): ejecute la API en su propia infraestructura.
* [Guía de inicio para desarrolladores](/en/contribute/developer-on-ramp/): ejecute la aplicación en local y contribuya.