> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craqui.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Seguridad de una app

> Dónde va el secreto, cómo cambiarlo sin cortar el servicio, cómo cuidar los tokens y qué hacer si algo se expone.

Tu app tiene acceso a datos de muchos negocios: las personas que los usan, su actividad, sus pagos. Quien tenga tu secreto o
tus tokens tiene ese mismo acceso. Esta página junta lo que tienes que cuidar.

## El secreto vive en tu servidor

* El secreto (`crq_cs_…`) va solo en el código que corre en tu servidor: en el gestor de secretos de tu
  plataforma o en una variable de entorno. **Nunca** en una página web, en una app de teléfono, en una extensión
  de navegador ni en un repositorio, aunque sea privado.
* Una app de teléfono o una web sin servidor no pueden guardar un secreto: cualquiera que la descargue lo lee.
  Si tu producto es una de esas, el flujo pasa por tu servidor, y el teléfono o la web hablan con tu servidor,
  nunca con Craqui directamente.
* `/oauth/token` y `/oauth/revoke` rechazan los pedidos que vienen de un navegador, y la API también.

## Cambia el secreto sin cortar el servicio

Una app puede tener **dos secretos activos** a la vez. Para cambiar el secreto:

1. En la app, **Credenciales → Nuevo secreto**. Cópialo: se muestra una sola vez.
2. Pon el secreto nuevo en tu servidor y despliega.
3. Confirma que tu servidor ya usa el nuevo: en **Credenciales**, el «Último uso» del secreto viejo deja de
   avanzar.
4. **Revoca** el viejo. Deja de funcionar en el acto, en el pedido siguiente.

Los tokens que ya emitiste siguen funcionando: el secreto solo se usa para pedir tokens.

## Cuida los tokens

* Guarda los refresh tokens **cifrados** en tu base de datos, cada uno junto a su `business_id`. Son la conexión
  con cada negocio: no tienen copia.
* Los access tokens duran una hora. Guárdalos en memoria o cifrados, nunca en el navegador de tu usuario.
* No escribas tokens, secretos ni códigos en logs, en mensajes de error ni en tu herramienta de monitoreo. Si
  necesitas identificar uno, usa sus últimos cuatro caracteres.
* El token va solo en el header `Authorization`. En la URL termina en los logs de cualquier proxy del camino, y
  la API lo rechaza ([`invalid_request`](https://docs.craqui.com/errors/invalid_request)).
* Renueva el refresh token de cada negocio desde un solo proceso a la vez. Dos renovaciones en paralelo con el
  mismo refresh token se ven como un robo y desconectan el negocio. Lee [Tokens](https://docs.craqui.com/apps/tokens.md).

## El flujo de conexión

* **PKCE, siempre.** Un `code_verifier` nuevo por cada intento, guardado en la sesión de servidor de esa
  persona. Sin el `code_verifier`, un código robado no sirve.
* **`state`, siempre.** Un valor nuevo por intento, que compruebas al volver. Evita que alguien le haga
  conectar a tu usuario el negocio de otra persona.
* **Comprueba `iss`.** Tiene que ser `https://api.craqui.com`.
* **Direcciones de retorno exactas y tuyas.** Solo `https://`, en tu dominio. Quita las de prueba que ya no
  uses: cada dirección registrada es un lugar al que puede llegar un código.
* **Tu página de retorno no filtra el código.** Cambia el código por tokens enseguida y redirige a otra página
  de tu web, sin el código en la URL. No cargues en la página de retorno scripts ni imágenes de terceros, y
  usa `Referrer-Policy: no-referrer` o `same-origin`.

## Si algo se expone

| Qué se expuso | Qué hacer |
| - | - |
| El secreto | Crea uno nuevo, ponlo en tu servidor y **revoca** el expuesto enseguida |
| Un refresh token | Revócalo en `/oauth/revoke`: desconecta ese negocio. Después pídele al propietario que conecte tu app de nuevo |
| Muchos tokens (tu base de datos) | Revoca el refresh token de cada negocio, cambia el secreto y escríbenos. Cada propietario tendrá que conectar tu app de nuevo |

Si ves algo raro en la Actividad de tu app, o un negocio te dice que su conexión aparece desconectada por
seguridad, escríbenos a soporte.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.