Autenticación y permisos
Cómo se usa la API key, cómo rotarla sin parar de facturar y por qué nunca ves datos de otra empresa.
La API key
Toda petición a /v1 lleva tu clave en el encabezado X-API-Key:
GET /v1/company HTTP/1.1
Host: api-sandbox.cufy.co
X-API-Key: TU_API_KEYO, en la terminal:
curl https://api-sandbox.cufy.co/v1/company \
-H "X-API-Key: TU_API_KEY"Cuatro cosas que conviene saber desde el principio:
- La clave fija empresa y ambiente. No hay encabezado, parámetro ni campo para cambiarlos.
- El secreto se muestra una sola vez, cuando se crea. Nadie te lo puede volver a mostrar: si lo pierdes, creas otra y revocas la perdida.
- Trátala como una contraseña. Guárdala en un almacén de secretos o en una variable de entorno del servidor. Nunca en el navegador, en la URL, en un argumento de línea de comandos, en los logs ni en Git.
- Si se te filtra, revócala y crea otra desde el panel. Ver Rotar una clave.
Una clave que falta, está mal escrita, expiró o fue revocada responde 401 INVALID_API_KEY. Todas las claves de tu cuenta pueden lo mismo, así que un 403 no es tu clave: es algo que la cuenta no puede hacer, como emitir en producción.
Rotar una clave
Rota cuando una clave se filtró, cuando se va alguien que la tenía, o cada cierto tiempo por higiene. No hace falta parar de facturar: las dos claves funcionan a la vez mientras dure el cambio.
En el panel, en API keys, crea una clave nueva y copia su secreto.
Despliega tu integración con la clave nueva y comprueba que emite y consulta bien.
Revoca la anterior desde el panel. Desde ese momento responde 401.
Revocar una clave no toca los documentos ya emitidos: siguen su curso y se consultan igual con la clave nueva.
Aislamiento entre empresas
Tu clave solo ve lo de tu empresa y tu ambiente. Un recurso de otra empresa responde 404, no 403, para no revelar siquiera que existe.
Esto vale para documentos, archivos, entregas, destinos y eventos de webhook, y claves. Los listados nunca traen elementos ajenos, y los cursores de paginación no sirven entre empresas.
Está comprobado: otra empresa que pida tu documento, tus archivos, su contenido, tu destino o tus eventos recibe 404 en todos los casos. Nadie puede usar la API para averiguar si un identificador tuyo existe.
Si integras varias empresas (por ejemplo, porque vendes software), usa una clave por empresa y guarda cada identificador junto a la empresa a la que pertenece. Un document_id de una empresa no existe para la otra.