Claves de API

Cada proyecto de Bitelio tiene una clave pública y cualquier número de claves secretas. La clave pública se genera una sola vez, al crear el proyecto, y solo puede llegar a POST /v1/track. Las claves secretas se crean bajo demanda — desde el panel o desde la API — y cada una lleva un conjunto explícito de alcances (scopes): la porción exacta de la API que puede tocar. Ya no existe un único secreto todopoderoso — crea una clave con alcance limitado por cada integración, y revoca cualquiera de ellas sin afectar al resto.

Encontrar tus claves

Abre tu proyecto y ve a Ajustes → General. La clave pública ocupa su propia tarjeta cerca de la parte superior, visible para cualquier miembro del proyecto — no hay nada que proteger, ya que solo puede llegar a /v1/track. Esa tarjeta incluye también un botón Rotar, visible para los miembros con el permiso apikeys:manage. Las claves secretas con alcance viven en la tarjeta Claves de API justo debajo. Esa tarjeta requiere el mismo permiso apikeys:manage para verse siquiera; sin él, verás un aviso de bloqueo en lugar de una lista.

Los dos tipos de claves

La clave pública es deliberadamente limitada: existe para que navegadores y apps móviles puedan registrar eventos mediante /v1/track sin ganar acceso al resto de la API. Si alguna vez se ve comprometida, la exposición se limita a /v1/track (crear o actualizar contactos y disparar flujos de trabajo mediante eventos registrados), no al resto de los datos de tu proyecto.

Aun así, puedes reemplazarla: Ajustes → General → Rotar, o POST /apikeys/public/rotate, genera una nueva pk_ y te devuelve tu proyecto con el nuevo valor. No hay ventana de solapamiento — la clave anterior deja de funcionar de inmediato, así que todo lo que siga usándola dejará de registrar eventos hasta que despliegues el reemplazo. Rotar requiere el permiso apikeys:manage y queda registrado en el registro de Actividad de tu proyecto.

Una clave secreta, en cambio, solo tiene el poder que le des mediante sus alcances — desde un único permiso (por ejemplo, solo email:send, para un servicio que únicamente envía correo transaccional) hasta casi todo lo que puede hacer un Owner. Bitelio deduce a qué proyecto apunta cada solicitud a partir de la propia clave, así que las llamadas a la API no llevan un parámetro de ID de proyecto por separado.

Alcances

Los alcances de una clave secreta se toman del mismo catálogo de permisos que da forma a los roles — campaigns:send, contacts:edit, email:send, y así sucesivamente. Otorga a una clave solo lo que necesita: una integración que envía correo transaccional necesita email:send y nada más; un panel de analítica de solo lectura necesita analytics:view.

Cinco permisos nunca pueden otorgarse a ninguna clave, sin importar quién la cree — son decisiones a nivel de cuenta o de aprobación que deben quedarse con una persona con sesión iniciada: apikeys:manage, team:manage, billing:manage, project:manage y campaigns:approve. Todos los demás permisos del catálogo pueden otorgarse.

Una clave tampoco puede superar a quien la crea: solo puedes repartir alcances que tú mismo tengas. Un Owner puede otorgar cualquier alcance otorgable; cualquier otra persona está limitada a los permisos de su propio rol.

El relay SMTP (Ajustes → SMTP) también comprueba los alcances — una clave usada como contraseña SMTP necesita el alcance email:send, o la conexión se rechaza en AUTH con un mensaje que nombra el alcance que falta.

Crear y revocar claves

Crear o revocar una clave requiere el permiso apikeys:manage — por defecto, solo los roles Owner y Admin lo tienen — y cada creación y revocación queda registrada en el log de auditoría del proyecto.

Para crear una: en la tarjeta Claves de API, haz clic en Crear clave, dale un nombre que reconozcas después ("Servicio de sincronización de pedidos", "Zapier"), elige sus alcances y, opcionalmente, establece una fecha de expiración. Su valor en texto plano se muestra exactamente una vez, en el diálogo de confirmación justo después de crearla — cópialo ahora. Bitelio solo almacena su hash SHA-256, así que el valor no puede volver a mostrarse, recuperarse ni enviarse por correo más tarde. Si lo pierdes, revócala y crea una de reemplazo.

Cada clave que hayas creado aparece en una tabla: su nombre, un prefijo corto para distinguir claves entre sí (sk_ más un puñado de caracteres — nunca el valor completo), sus alcances, cuándo se usó por última vez y cuándo se creó. Revocar una clave la detiene de inmediato y para siempre; el resto de las claves del proyecto siguen funcionando exactamente igual que antes. No hay forma de deshacerlo — crear una clave nueva con los mismos alcances es la única manera de volver atrás.

Autenticar solicitudes

Ambos tipos de clave se envían de la misma forma: como un token Bearer en el encabezado Authorization, en cada solicitud.

curl https://api.bitelio.com/v1/send \
  -H "Authorization: Bearer $BITELIO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "user@example.com", "subject": "Hello", "body": "<p>Hi</p>" }'

const response = await fetch('https://api.bitelio.com/v1/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.BITELIO_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: 'user@example.com',
    subject: 'Hello',
    body: '<p>Hi</p>',
  }),
});

import os
import requests

response = requests.post(
    'https://api.bitelio.com/v1/send',
    headers={
        'Authorization': f"Bearer {os.environ['BITELIO_SECRET_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'to': 'user@example.com',
        'subject': 'Hello',
        'body': '<p>Hi</p>',
    },
)

Usar una clave en un endpoint fuera de su tipo produce un 401 con el código INVALID_API_KEY — por ejemplo, una clave pk_ contra /v1/send. Usar una clave secreta válida pero sin el alcance que exige el endpoint produce un 403.

Almacenar claves de forma segura

• Mantén las claves secretas (sk_) en variables de entorno del lado del servidor — .env.local mientras desarrollas, el gestor de secretos de tu plataforma en producción. Nunca deben terminar en un build de frontend.
• Las claves públicas (pk_) pueden viajar en código de navegador, pero no las trates como totalmente públicas — si alguien empieza a abusar de tu endpoint de seguimiento, rota la clave desde Ajustes → General y vuelve a desplegar tu código de cliente.
• Da a cada integración su propia clave, con el alcance limitado a lo que necesita, en lugar de compartir una clave en todas partes. Una clave filtrada te cuesta entonces el acceso de una integración, no el de todo el proyecto.
• Usa proyectos de Bitelio separados para staging y producción, de modo que una clave de staging filtrada no tenga alcance sobre los datos de producción.

Responder ante una clave comprometida

1. Revoca la clave de inmediato — desde Ajustes → Claves de API, o con POST /apikeys/:id/revoke. Una vez que su reemplazo esté desplegado en todos los sitios donde se usaba la anterior, ya está; no hay ningún par compartido que reemitir. En el caso de la clave pública no hay nada que revocar: rótala, desde Ajustes → General o con POST /apikeys/public/rotate.
2. Revisa la pestaña Actividad en busca de envíos, ediciones de contactos o cambios de campaña que no reconozcas dentro de la ventana de exposición.
3. Consulta Facturación → Consumo en busca de picos de uso que indiquen abuso.
4. Si encuentras actividad no autorizada, pásale los ID de solicitud de esas entradas a soporte.

Referencia de la API

• POST /apikeys — crea una clave secreta con alcance. Cuerpo: { name, scopes, expiresAt? }. Requiere apikeys:manage; a una clave solo se le pueden otorgar alcances que tú mismo tengas. Devuelve los metadatos de la clave más su valor en texto plano (key) — la única respuesta que lo contendrá.
• GET /apikeys — lista las claves del proyecto: nombre, prefijo, alcances y marcas de tiempo. Nunca el valor en texto plano, ni tampoco el hash almacenado.
• POST /apikeys/:id/revoke — revoca una clave de inmediato, sin tocar el resto. Idempotente: revocar una clave ya revocada simplemente devuelve su revokedAt existente.
• POST /apikeys/public/rotate — reemplaza la clave pública (pk_) del proyecto. Sin cuerpo. Devuelve el proyecto con su nuevo valor de public; la clave anterior deja de funcionar al instante.

Las cuatro requieren el permiso apikeys:manage en una sesión de panel con inicio de sesión — ninguna puede llamarse con una clave de API.