Autenticación de la Partner API: claves Bearer ec_live_, rotación y errores 401
Cada petición a la Partner API lleva la clave secreta de la cuenta en el encabezado Authorization: Bearer ec_live_…, enviada desde tu servidor. Cada cuenta de easyCoexistence tiene una clave, que se crea en el panel, en Profile, Developers, o pidiéndole a un asistente de IA que ejecute create_api_key, y se muestra una sola vez. Rotarla emite una clave nueva y termina la anterior al instante; una clave ausente o incorrecta devuelve 401 unauthorized.
El prefijo con el que empieza cada clave de la Partner API, enviada en cada petición como Authorization: Bearer.
Claves que tiene una cuenta a la vez; cada conexión hecha con ella pertenece a esa cuenta.
Estado para una clave ausente o no válida, con el código de error unauthorized y un mensaje que indica el encabezado esperado.
Momentos en que se muestra la clave completa: al crearla o rotarla; después solo son visibles sus primeros caracteres.
¿Cómo se autentica una petición?
Con la clave como token Bearer en el encabezado Authorization de cada petición a https://easycoexistence.com/api/v1. No hay firma ni alcance adicional: la clave identifica la cuenta, y todo lo que una petición crea o lee pertenece a esa cuenta. Los cuerpos son JSON, y cada error llega como un objeto con un código y un mensaje.
curl https://easycoexistence.com/api/v1/connections \
-H "Authorization: Bearer $EC_API_KEY"¿Dónde se crea la clave?
En el panel o desde un asistente de IA, con el mismo resultado. En el panel, abre Profile, luego Developers, y pulsa Create API key. En Claude, ChatGPT u otro asistente conectado al servidor MCP de easyCoexistence, pídele que configure la Partner API: get_partner_setup muestra qué falta y create_api_key devuelve la clave. En ambos casos la clave completa aparece una vez, así que guárdala de inmediato en los secretos de tu backend.
¿Por qué la clave se muestra una sola vez?
Porque solo se guarda un hash de ella. easyCoexistence conserva el hash para verificar cada petición, además de los primeros caracteres de la clave, ec_live_ y seis más, para que el panel pueda mostrar qué clave está activa y cuándo se creó. Una clave perdida no puede volver a mostrarse; rotarla la reemplaza.
¿Cómo se rota o revoca la clave?
En un solo paso, y la clave anterior deja de funcionar en ese mismo momento, sin periodo de gracia, ya que una filtración es el motivo habitual para rotar. La clave nueva se muestra una vez, igual que la primera:
- Panel: Profile, Developers, Rotate key.
- MCP:
create_api_keyconreplace_existingen true. Sin ese parámetro la herramienta se niega mientras exista una clave, para que una integración en marcha no se rompa por accidente. - Para cortar todo acceso, revoca: Revoke en el panel, o
revoke_api_keycon confirm en true. Las peticiones fallan entonces hasta que se cree una clave nueva.
¿Qué devuelve una clave ausente o incorrecta?
Un 401 con el código unauthorized, para una petición sin encabezado Authorization, una clave que no empieza por ec_live_, o una clave que fue rotada o revocada. El mensaje indica el encabezado que espera. Cuando las peticiones fallidas llegan sin parar desde una misma dirección, la API responde 429 rate_limited, con los segundos que hay que esperar antes de reintentar.
{
"error": {
"code": "unauthorized",
"message": "Missing or invalid API key. Send `Authorization: Bearer ec_live_...`."
}
}¿Qué más puede rechazar una clave válida?
Una clave válida autentica la cuenta, y el estado de la cuenta sigue aplicando. Estas respuestas llegan con la misma forma de error:
- 402
billing_required: la cuenta aún no tiene tarjeta, así que no puede iniciar sesiones de conexión. - 404
not_found: el id no pertenece a ninguna conexión, canal o sesión de esta cuenta, incluidas las de otras cuentas. - 409 removed: la conexión fue eliminada, así que su webhook no puede cambiar.
- 402 suspended: la conexión está suspendida tras una suscripción vencida; reconéctala primero.
- 429
cap_reachedorate_limited: demasiadas sesiones de conexión abiertas, o demasiadas creadas en esta hora.
Errores comunes
- Poner la clave en el código del front-end. Cualquiera que abra la página puede leerla, crear conexiones que se facturan a tu cuenta y obtener los tokens de tus clientes con ?credentials=1.
- Rotar antes de que tu backend pueda usar la clave nueva. La anterior se detiene al instante, así que cada petición falla con 401 hasta desplegar la nueva.
- Crear la clave en una conversación que compartes. create_api_key la devuelve en el chat, donde queda en el historial, así que rótala si esa conversación se comparte.
- Guardar la clave entre comillas. Todo lo que va después de Bearer se lee como la clave, así que un valor entre comillas nunca coincide y cada petición recibe 401.
easyCoexistence da a cada cuenta una clave de la Partner API, para que tu backend pueda conectar los números de WhatsApp de tus clientes y sus cuentas de Instagram, Facebook, TikTok, YouTube y LinkedIn, y más canales, y luego leer las credenciales de cada conexión y enrutar sus eventos. De US$ 9 a US$ 0.75 por conexión al mes, bajando a medida que agregas conexiones, y los primeros 3 días gratis.
Preguntas frecuentes
¿Una cuenta puede tener más de una clave de API?
No. Una cuenta tiene una clave a la vez, y crear una nueva reemplaza la anterior. Las claves separadas significan cuentas de easyCoexistence separadas, cada una con sus propias conexiones y su propia factura.
¿Las claves de la Partner API caducan?
No. Una clave funciona hasta que se rota o revoca, o hasta que easyCoexistence la termina por abuso de las reglas de Meta.
¿Mis clientes necesitan mi clave para conectarse?
No. Solo abren el enlace de conexión alojado, que lleva su propio id de sesión. La clave permanece en tu servidor y solo la usa tu backend.
¿La clave de la API es lo mismo que el secreto de firma de eventos?
No. La clave autentica tus peticiones a la API. El secreto de firma, que se muestra una vez al configurar una URL de eventos de estado, permite a tu endpoint verificar los eventos que envía easyCoexistence.
Sigue leyendo
Conecta tu primer canal en dos minutos.
Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.
- 3 días gratis
- Cancela cuando quieras
- Solo APIs oficiales
- Monitorizado 24/7
Verificado el