Claves de API

Cada llamada a la API REST de Joryio se autentica con una clave de API. Las claves se limitan a un único espacio de trabajo, incluyen una lista explícita de permisos y se pueden restringir a un conjunto de direcciones IP.

Todos los endpoints de esta página son relativos a la URL base: https://api-eu1.joryio.com. Consulta Resumen de API.

Crear una clave

1. Abre el panel de Joryio y ve a Configuración → Claves de API.
2. Haz clic en Crear clave de API.
3. Asigna un nombre a la clave y, opcionalmente, una descripción que verán tus compañeros.
4. Añade opcionalmente una lista de IP permitidas: lista de CIDR o IP individuales separada por comas o espacios. Déjala vacía para permitir cualquier IP.
5. Marca los permisos que necesita la clave. Elige el conjunto más pequeño que funcione; consulta el catálogo de ámbitos más abajo.
6. Haz clic en Crear clave.

Se muestra una sola vez

El valor completo de la clave se muestra exactamente una vez, justo después de crearla, y nunca más. Cópialo en tu gestor de secretos (1Password, Vault, AWS Secrets Manager, etc.) antes de cerrar el diálogo. Si lo pierdes, elimina la clave y crea otra: Joryio no puede recuperar la original.

El formato de la clave es jry_live_<aleatorio> para claves de producción y jry_test_<aleatorio> para claves de prueba. El prefijo visible de la clave (jry_live_abc123) aparece en la lista de claves del panel y en los registros de servidor, para que puedas identificar qué hizo cada clave sin exponer el valor completo.

Usar una clave

Envía la clave como token bearer en el encabezado Authorization de cada solicitud:

GET /users/by-user-id/user_123
Host: api-eu1.joryio.com
Authorization: Bearer jry_live_98f31a72…
Content-Type: application/json

Catálogo de ámbitos

Los permisos siguen el formato <recurso>:<verbo>. Los verbos usados son:

Verbo	Significado	Ejemplo
read	Enumera u obtiene registros existentes	users:read, campaigns:read
write	Crea o actualiza registros	users:write, segments:write
send	Activa una acción de entrega o envío	campaigns:send
delete	Elimina registros permanentemente	users:delete, campaigns:delete
track	Envía eventos de analítica	events:track
activate	Inicia, pausa o reanuda un flujo activo	canvas:activate
alias	Vincula o desvincula identificadores alternativos	users:alias
merge	Combina dos perfiles de usuario	users:merge
export	Exporta registros en bloque	users:export

A continuación está el catálogo público completo; también lo devuelve GET /api-keys/permissions:

Eventos

Ámbito	Qué permite
events:track	Enviar eventos personalizados desde tus servidores o SDK.
events:read	Consultar eventos que se han registrado.

Usuarios

Ámbito	Qué permite
users:read	Consultar perfiles y atributos de usuario por ID.
users:write	Crear o actualizar atributos y propiedades de usuario.
users:delete	Eliminar perfiles de usuario permanentemente (RGPD / derecho de supresión).
users:alias	Vincular o desvincular ID externos y alias de email de un usuario.
users:merge	Combinar dos perfiles de usuario en uno.
users:export	Exportar perfiles de usuario en bloque para análisis sin conexión.

Campañas

Ámbito	Qué permite
campaigns:read	Enumerar campañas y ver su configuración.
campaigns:write	Crear o editar borradores de campaña mediante API.
campaigns:send	Activar el envío de una campaña a un usuario o segmento concreto.
campaigns:delete	Eliminar campañas permanentemente de este espacio de trabajo.

Segmentos

Ámbito	Qué permite
segments:read	Enumerar segmentos y ver recuentos de pertenencia.
segments:write	Crear o actualizar definiciones de segmentos.
segments:delete	Eliminar segmentos y su historial permanentemente.

Recorridos de usuario

Ámbito	Qué permite
canvas:read	Enumerar recorridos de usuario e inspeccionar su grafo de pasos.
canvas:write	Crear o editar borradores de recorridos de usuario.
canvas:activate	Iniciar, pausar o reanudar un recorrido de usuario activo.
canvas:delete	Eliminar recorridos de usuario y su historial.

Plantillas

Ámbito	Qué permite
templates:read	Obtener contenido de plantillas de email, SMS y push.
templates:write	Crear o editar plantillas de mensajes reutilizables.
templates:delete	Eliminar plantillas de Brand Studio permanentemente.

Suscripciones

Ámbito	Qué permite
subscriptions:read	Ver el estado de consentimiento de un usuario por canal.
subscriptions:write	Suscribir o dar de baja usuarios de grupos y canales.

Apps y claves de SDK

Ámbito	Qué permite
apps:read	Enumerar las apps y claves de SDK registradas en este espacio de trabajo.
apps:write	Añadir, rotar o eliminar claves de SDK para apps móviles y web.

Biblioteca de recursos

Ámbito	Qué permite
assets:read	Obtener imágenes, fuentes y otros medios compartidos.
assets:write	Subir, renombrar o eliminar archivos en la biblioteca de recursos.

Entidades

Ámbito	Qué permite
entities:read	Consultar registros de entidades (productos, artículos, lugares…).
entities:write	Crear o actualizar registros y propiedades de entidades.

Analítica

Ámbito	Qué permite
analytics:read	Obtener métricas agregadas, embudos y datos de informes.

Entregabilidad

Ámbito	Qué permite
email_suppression:read	Inspeccionar la lista de supresión de email (rebotes, quejas y manual).
email_suppression:write	Añadir o eliminar entradas de la lista de supresión de email.
sms_suppression:read	Inspeccionar la lista de supresión de SMS (respuestas STOP y fallos).
sms_suppression:write	Añadir o eliminar números de teléfono de la lista de supresión de SMS.

Límites de frecuencia

Ámbito	Qué permite
touching_rules:read	Inspeccionar reglas de límite de frecuencia y sus contadores actuales.
touching_rules:write	Crear, editar o eliminar reglas de límite de frecuencia.

WhatsApp

Ámbito	Qué permite
whatsapp:read	Leer la configuración de la cuenta WhatsApp Business.
whatsapp:write	Actualizar la configuración de la cuenta WhatsApp Business.

Agentes de IA

Ámbito	Qué permite
ai_agents:read	Enumerar agentes de IA y su configuración.
ai_agents:write	Crear o editar agentes de IA y sus opciones de proveedor.

Lista de IP permitidas

Puedes restringir una clave a un conjunto fijo de IP de origen. Cuando la lista de IP permitidas está vacía, se aceptan solicitudes desde cualquier IP (es el valor predeterminado). Cuando tiene entradas, solo pasan las solicitudes cuya IP de origen coincida con al menos una entrada.

Sintaxis aceptada

• Dirección IPv4 simple: 203.0.113.42.
• Rango CIDR IPv4: 10.0.0.0/24, 192.168.1.0/16.
• Dirección IPv6: solo coincidencia exacta (todavía no hay CIDR para IPv6).

Combina varias entradas separándolas con comas en el panel:

10.0.0.0/24, 203.0.113.42, 2001:db8::1

Resolución de IP de origen

La IP de cliente se resuelve desde el encabezado de confianza de la red perimetral (se establece de nuevo en cada solicitud en el borde, por lo que un valor proporcionado por el cliente no puede sobrevivir), con la dirección de conexión del proxy de confianza como alternativa. La entrada X-Forwarded-For situada más a la izquierda y controlada por el cliente no se usa deliberadamente, para que no se pueda falsear la lista de IP permitidas. Las direcciones IPv6 asignadas a IPv4 (::ffff:203.0.113.42) se normalizan a su forma IPv4 antes de comparar.

Forma de la solicitud rechazada

Cuando una solicitud procede de una IP no permitida, la API devuelve 401 No autorizado con:

{
  "statusCode": 401,
  "message": "Request IP is not allowed for this API key",
  "timestamp": "2026-05-12T08:14:00.000Z",
  "path": "/users"
}

El rechazo se registra en el servidor con el prefijo de la clave y la IP infractora para que puedas auditarlo.

Endpoints de gestión de claves

Las claves se gestionan mediante el panel (Configuración → Claves de API) o la API:

Método	Endpoint	Descripción
GET	/api-keys/permissions	Enumerar todos los ámbitos que se pueden conceder
POST	/api-keys	Crear una clave (?environment=live o test; cuerpo: name, description?, permissions[], ipAllowlist?, expiresAt?): el valor completo se devuelve una vez
GET	/api-keys	Enumerar claves del espacio de trabajo
GET	/api-keys/:apiKeyId	Obtener metadatos de una clave
PUT	/api-keys/:apiKeyId	Actualizar nombre, descripción, permisos, lista de IP permitidas o vencimiento
POST	/api-keys/:apiKeyId/revoke	Desactivar una clave (deja de autenticar de inmediato)
POST	/api-keys/:apiKeyId/rotate	Generar un valor de clave nuevo manteniendo los mismos permisos; el valor se devuelve una vez
DELETE	/api-keys/:apiKeyId	Eliminar una clave permanentemente (devuelve 204)

Quien realiza la llamada nunca puede conceder a una clave ámbitos que no posee.

Campos de respuesta de lista

GET /api-keys devuelve { "apiKeys": [...] }, con cada clave de la siguiente forma (el valor completo y su hash nunca se exponen):

{
  "apiKeys": [
    {
      "id": "7c2e4f6a-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "name": "ServerSide Updates",
      "description": "Used by our backend to send events.",
      "keyPrefix": "jry_live_98f31a72",
      "permissions": ["events:track", "users:write"],
      "lastUsedAt": "2026-05-12T08:14:00.000Z",
      "expiresAt": null,
      "isActive": true,
      "createdAt": "2026-02-19T12:00:00.000Z",
      "updatedAt": "2026-02-19T12:00:00.000Z"
    }
  ]
}

La ipAllowlist de la clave se establece al crear o actualizar; se aplica en cada solicitud, pero no se incluye en la respuesta de lista.

Errores habituales

Estado	Mensaje	Qué comprobar
401	Invalid API key format	Falta el encabezado, tiene un formato incorrecto o no empieza por jry_.
401	Invalid or expired API key	La clave se revocó, eliminó o superó su expiresAt.
401	Request IP is not allowed for this API key	La IP de origen no coincidió con ninguna entrada permitida; consulta Lista de IP permitidas.
403	This API key does not have the required permissions: ...	La clave es válida, pero no tiene el ámbito necesario para el endpoint.
403	ORG_HARD_SUSPENDED: organization is suspended. Read-only access only.	La organización propietaria está suspendida; contacta con soporte.

Rotar una clave

Llama a POST /api-keys/:apiKeyId/rotate (o usa el panel): la clave recibe un valor secreto nuevo (y un keyPrefix nuevo), que se devuelve exactamente una vez en la respuesta, y conserva el nombre, los ámbitos y el ID. Todo lo que siga llamando con el valor antiguo empieza a fallar de inmediato, así que despliega primero el valor nuevo donde puedas y usa el keyPrefix en tus registros de acceso para encontrar integraciones que aún usan la clave antigua. Si prefieres una rotación sin tiempo de inactividad, crea una segunda clave con los mismos ámbitos, migra a quienes realizan llamadas y elimina después la clave antigua.