Autenticación y llaves de API

Llaves de API

Envía la llave como token Bearer en cada solicitud:

Authorization: Bearer sk_live_…

• Formato: sk_live_ seguido de 43 caracteres. Cualquier otra cosa responde 401 sin llegar siquiera a nuestra base de datos.
• Cada llave es real: no hay modo de prueba. Etiqueta los leads de prueba (por ejemplo docs-test) para encontrarlos y quitarlos.
• La llave se muestra una sola vez, al crearla. Solo guardamos un hash con clave, así que nadie, ni siquiera SpaceKru, puede volver a mostrártela.
• Hasta 5 llaves activas por cuenta. Nombra cada llave por la herramienta que la usa ("Zapier", "Formulario web", "Sincronización ERP") para revocar una sin tocar las demás.

Quién puede crear llaves

Solo el dueño de la cuenta, en Integraciones → API y Webhooks (nombres de hasta 100 caracteres). El mismo panel muestra el último uso de cada llave, las solicitudes de los últimos 30 días y cada suscripción de webhook.

Permisos (scopes)

• Solo lectura (read): cada GET excepto webhooks y conversaciones.
• Lectura y escritura (read + write): todo lo que crea o cambia datos, y cada operación de /subscriptions.
• Conversaciones con IA (conversations, opcional, solo con lectura y escritura): las operaciones de /conversations. Gastan tokens de IA, por eso el dueño lo concede de forma explícita al crear la llave.

Una llave sin el permiso que necesita una operación responde 403 INSUFFICIENT_SCOPE.

Módulos del plan (403)

Algunas operaciones necesitan un módulo de tu plan, el mismo que necesita la app: crm (leads, deals, campañas), sales_os (productos, cotizaciones, órdenes) y scheduler (reservas). Sin él la respuesta es 403 MODULE_NOT_AVAILABLE. Hoy todos los planes de pago incluyen los tres módulos.

Idioma de las respuestas

error.message llega en inglés o en español. Envía Accept-Language: es (o en) para elegir; sin él, se usa el idioma del perfil de la persona que creó la llave. El header Content-Language te dice cuál recibiste. Los code de error, los nombres de campos, los nombres de eventos y details[].issue nunca cambian: decide con ellos, no con el mensaje.

Requisitos del plan (402)

La API solo funciona mientras la cuenta esté en un plan de pago activo (cuenta la prueba gratuita de 7 días). Si no, cada solicitud responde 402 PLAN_UPGRADE_REQUIRED con uno de estos mensajes:

• No hay periodo de gracia: un pago que falla pausa la API de inmediato (en aproximadamente un minuto).
• Las llaves no se borran. Cuando la cuenta vuelve a un plan de pago, las mismas llaves y webhooks funcionan de nuevo.
• Si no podemos verificar el plan por un momento, recibes 503 ELIGIBILITY_UNAVAILABLE con Retry-After: 10. Falla cerrado: reintenta, nunca es un pase libre.

401 vs 402 vs 403

Revocar y rotar llaves

• Revoca una llave en Integraciones → API y Webhooks. Deja de funcionar en la siguiente solicitud: no hay caché.
• Revocar una llave también desactiva las suscripciones de webhook que creó (disabled_reason: "key_revoked"). Las de otras llaves no se tocan.

Para rotar una llave sin interrupciones:

1. Crea una llave nueva con el mismo acceso.
2. Ponla en tu integración (variable de entorno, conexión de Zapier/Make/n8n).
3. Revisa en el panel que la llave nueva tenga un "Último uso" reciente.
4. Revoca la llave vieja. Si creó webhooks, suscríbelos de nuevo con la llave nueva (y si usaban exclude_own_changes, ahora omiten los cambios de la llave nueva).

Seguridad y buenas prácticas

• Solo de servidor a servidor. La API no envía headers CORS, así que los navegadores bloquean llamadas desde páginas web, a propósito. Una llave en código de front-end, una app móvil o un repositorio público puede ser robada; mantenla en un servidor o en tu herramienta de automatización.
• Guarda las llaves como secretos: variables de entorno, un gestor de secretos o el almacén de credenciales de Zapier, Make o n8n.
• Mínimo privilegio: una llave de Solo lectura para reportes; Conversaciones con IA solo para la llave de tu integración de chat.
• Una llave por integración, para que revocar una nunca rompa las demás.
• Verifica la firma de cada webhook y rechaza marcas de tiempo viejas: mira Verificar firmas.
• Aislamiento por cuenta: una llave solo puede ver su propia cuenta. Un id de otra cuenta responde 404 igual que uno que no existe, también dentro de un body (lead_id, product_id…).
• Los destinos de los webhooks están restringidos a hosts públicos https:// en el puerto 443, verificados en cada entrega; nunca se siguen redirecciones.

Ejemplo: comprueba una llave

curl "https://app.spacekru.com/api/public/v1/ping" \
  -H "Authorization: Bearer $SPACEKRU_API_KEY"

const res = await fetch('https://app.spacekru.com/api/public/v1/ping', {
  headers: {
    Authorization: `Bearer ${process.env.SPACEKRU_API_KEY}`,
  },
});
const body = await res.json();
if (!res.ok) {
  // Branch on body.error.code; quote body.error.request_id to support.
  throw new Error(`${body.error.code}: ${body.error.message} (request ${body.error.request_id})`);
}
console.log(body);

import os

import requests

r = requests.get(
    "https://app.spacekru.com/api/public/v1/ping",
    headers={
        "Authorization": f"Bearer {os.environ['SPACEKRU_API_KEY']}",
    },
    timeout=30,
)
body = r.json()
if not r.ok:
    # Branch on body["error"]["code"]; quote body["error"]["request_id"] to support.
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} (request {body['error']['request_id']})")
print(body)