Autenticación

Cada petición se autentica con una clave de API enviada en la cabecera Authorization, con el esquema Bearer.

curl https://api.joinotify.com/templates \
  -H 'Authorization: Bearer sk_live_xxx'

Formato del token

sk_live_AbCdEf0123456789abcdefgh
│  │    └── 32 caracteres aleatorios (192 bits de entropía)
│  └── entorno: live o test
└── prefijo fijo

Los primeros 14 caracteres forman el prefijo (sk_live_AbCdEf). Se muestra en el panel y en los listados para que identifiques la clave sin revelar el secreto.

El token nunca va en la URL

La documentación de Meta muestra ejemplos con ?access_token= en la query string. En Joinotify eso no funciona ni funcionará — los parámetros de URL se filtran en registros de servidor, historiales de navegador y cabeceras Referer.

# Correcto
curl https://api.joinotify.com/v1/{WABA_ID} \
  -H 'Authorization: Bearer sk_live_xxx'

# No funciona
curl 'https://api.joinotify.com/v1/{WABA_ID}?access_token=sk_live_xxx'

Crear una clave

Desde el panel, en Claves de API, o desde la propia API con una clave existente:

curl -X POST https://api.joinotify.com/keys \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "integracion-erp", "environment": "live" }'

201 Created

{
  "data": {
    "id": "key_01J8ZK...",
    "name": "integracion-erp",
    "prefix": "sk_live_AbCdEf",
    "environment": "live",
    "createdAt": "2026-07-27T14:02:11.482Z",
    "secret": "sk_live_AbCdEf0123456789abcdefgh"
  },
  "warning": "Store the \"secret\" now — it will not be shown again."
}

El campo secret aparece solo en esa respuesta. Guardamos únicamente el hash SHA-256 del secreto — no hay manera de recuperarlo después.

Editar una clave

Renombrar la clave o cambiar a qué números llega, sin cambiar el secreto:

curl -X PATCH https://api.joinotify.com/keys/key_01J8ZK...   -H 'Authorization: Bearer sk_live_xxx'   -H 'Content-Type: application/json'   -d '{ "allowedPhoneNumberIds": ["1555000111", "1555000222"] }'

Es el camino de quien conectó un segundo WhatsApp y quiere que la clave que ya está en producción envíe también por él: el sk_… sigue siendo el mismo, así que ningún .env, plugin o flujo no-code hay que actualizar. El nuevo alcance vale ya en la siguiente petición.

allowedPhoneNumberIds sustituye la lista entera — envía los números a los que la clave debe llegar, no solo los nuevos. Una lista vacía devuelve la clave a todos los números de la cuenta, incluidos los que conectes después. Omitir el campo no toca el alcance.

environment no es editable: está grabado en el propio secreto (sk_live_… / sk_test_…). Para cambiar de entorno, crea otra clave. Una clave ya revocada responde 409 key_revoked — la revocación no tiene deshacer.

Listar y revocar

# Listar (nunca devuelve secretos)
curl https://api.joinotify.com/keys \
  -H 'Authorization: Bearer sk_live_xxx'

# Revocar
curl -X DELETE https://api.joinotify.com/keys/key_01J8ZK... \
  -H 'Authorization: Bearer sk_live_xxx'

La revocación es inmediata: la siguiente petición con esa clave ya recibe 401 authentication. Revocar una clave ya revocada devuelve 200 — la operación es idempotente, así que repetirla no rompe nada.

Buenas prácticas

Una clave por integración. ERP, tienda y chatbot con claves separadas. Cuando una se filtra, revocas solo esa.

Rota periódicamente. Crea la clave nueva, publícala, confirma que el tráfico migró (el panel muestra lastUsedAt por clave) y solo entonces revoca la antigua. Como ambas conviven, la rotación no tiene indisponibilidad.

Nunca en el front-end. La clave da acceso total a tu cuenta. Vive en el servidor, en una variable de entorno o un gestor de secretos — jamás en código de navegador, aplicación móvil o repositorio.

¿Se filtró? Revoca primero. Revocar tarda un segundo; investigar puede llevar horas.

Errores de autenticación

Código HTTP	type	Causa
401	authentication	Cabecera ausente, formato inválido, clave desconocida o revocada.
403	tenant_inactive	La cuenta está suspendida o cancelada. Habla con soporte.

401 Unauthorized

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication"
  }
}

Los entornos live y test

Las claves pueden crearse como live o test. Hoy el prefijo sirve para que distingas credenciales en tus propios sistemas y registros.

No hay sandbox

No existe un entorno de pruebas aislado: una clave sk_test_ envía mensajes reales y se factura como cualquier otra. Para probar sin impacto, usa un número de destino propio.