Copiar para IA

Autenticación

Aprende a estructurar tus peticiones autenticadas hacia los servidores de Cord.

Bearer Tokens

La API de Cord utiliza tokens al portador (Bearer Tokens) para autenticar las peticiones entrantes. Debes enviar la API Key que generaste en el panel de control como un encabezado HTTP Authorization.

Todas las peticiones deben realizarse a través de HTTPS. Las peticiones sin autenticación o enviadas vía HTTP plano fallarán.

Ejemplo de Petición:

curl -X GET "https://cordhq.app/api/v1/cotizaciones" \
     -H "Authorization: Bearer sk_live_tU..."

Claves Secretas vs Publicables

Cord tiene tres tipos de llave:

1. Secretas (sk_): solo en tus servidores. De solo lectura o de lectura y escritura sobre toda la API.
2. Restringidas (rk_): solo en tus servidores, con permiso por recurso (none, read o write). Úsalas para darle a una integración de terceros exactamente lo que necesita. Ver llaves restringidas.
3. Publicables (pk_): para el navegador, con una lista fija de rutas.

Enmascaramiento Automático de Datos

Las claves publicables tienen restricciones de seguridad automáticas impuestas por la API. Por ejemplo, si consultas la API de Productos usando una clave publicable, el servidor de Cord omitirá automáticamente el campo costo (margen) para garantizar que los visitantes de tu sitio web no puedan descubrir tus márgenes de ganancia.

Además, una Publishable Key solo puede usarse en cuatro rutas: GET /api/v1/productos, POST /api/v1/cotizaciones, GET /api/v1/elements/config y POST /api/v1/elements/ai-draft. Cualquier otra responde 403 insufficient_scope. La petición también debe enviar un header Origin o Referer que coincida con los dominios permitidos de tu organización, configurados en Ajustes › Cotizador embebible. Una pk_live_ sin dominios configurados responde 403 origin_allowlist_required; una pk_test_ se acepta desde cualquier origen.

Llaves restringidas

Una llave rk_ lleva un nivel por recurso. Cord deriva el recurso de la ruta, así que una ruta nueva de la API nace prohibida para las llaves restringidas existentes hasta que le des permiso.

Recurso	Rutas
cotizaciones	/api/v1/cotizaciones/*
clientes	/api/v1/clientes/*
productos	/api/v1/productos/*
facturas	/api/v1/facturas/*
cobranza	/api/v1/cobranza
tareas	/api/v1/tareas
eventos	/api/v1/events
webhooks	/api/v1/webhooks/*
elements	/api/v1/elements/*
test_helpers	/api/v1/test_helpers/*
setup	/api/v1/setup/*

read permite GET; write permite además crear, editar y las acciones. GET /api/v1/me responde con cualquier llave secreta o restringida. En el servidor MCP, una llave restringida aplica el mismo nivel por recurso a cada herramienta (ver permisos por herramienta). Sin permiso, la respuesta es 403 insufficient_permissions y nombra el recurso.

IPs permitidas

A una llave sk_ o rk_ le puedes fijar hasta 20 IPs o rangos CIDR (IPv4 o IPv6). Cord compara la IP de origen que registra su red de entrega, no un header que el cliente pueda escribir, así que X-Forwarded-For no sirve para saltarse la lista. Una petición desde otra IP responde 403 ip_not_allowed y queda en la bitácora de tu organización, una vez por hora por IP.

Las Publishable Keys se limitan por dominio en Ajustes › Cotizador embebible, no por IP.

Vencimiento y rotación

Al crear una llave puedes elegir que venza en 7, 30, 90 o 365 días; después responde 401 key_expired. Rotar crea una llave nueva con los mismos permisos, IPs y versión de la API, y deja la anterior viva el tiempo que elijas (inmediato, 1 hora, 24 horas o 7 días) mientras actualizas tus sistemas. La llave en gracia ya no cuenta contra el límite de tu plan. Crear, editar, rotar y revocar llaves queda registrado en la bitácora con quién y desde qué IP.

Llaves incluidas por plan

Cada plan incluye un número máximo de llaves activas: 2 en Gratis, 5 en Starter, 20 en Profesional, 50 en Scale y 200 en Developer. Cuentan las llaves secretas, restringidas y publicables que no están revocadas, vencidas ni en periodo de gracia por una rotación; las conexiones autorizadas por OAuth (Zapier, Make) no cuentan. Al llegar al tope, el Workbench no te deja crear otra hasta que revoques una.

Si tu organización queda con más llaves activas de las que incluye su plan (por ejemplo, después de bajar de plan), las más antiguas siguen funcionando y las que exceden el cupo responden 402 subscription_key_limit hasta que revoques llaves o subas de plan.

Comprobación Rápida de Identidad

Si necesitas probar si tu clave de API está funcionando correctamente y a qué cuenta pertenece, puedes utilizar el endpoint me:

curl -X GET "https://cordhq.app/api/v1/me" \
     -H "Authorization: Bearer sk_live_tU..."