Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

Claves de API

Crea claves de API con acceso total o solo de envío, limítalas a un dominio o a una bandeja de entrada y gestiónalas.

Una clave de API es el secreto que tu código envía en cada solicitud. Crea una en Claves de API en el panel, o con la propia API. La clave se muestra una sola vez, al crearla, así que guárdala en tu gestor de secretos.

curl https://api.billionsend.com/emails \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@example.com",
    "to": "success@simulator.amazonses.com",
    "subject": "Hola",
    "text": "Hola."
  }'

Las claves empiezan por bs_. BillionSend guarda solo un hash de la clave, así que una clave perdida no se puede volver a mostrar: revócala y crea una nueva.

Crear una clave

En el panel, abre Claves de API y elige Crear clave de API. Pueden hacerlo propietarios, administradores y desarrolladores; consulta los roles del equipo. Elige:

  • Nombre: de 1 a 80 caracteres, para distinguir las claves. Puedes renombrarla después.
  • Permiso: Acceso total o Solo envío.
  • Dominio: Cualquier dominio, o un dominio verificado de tu equipo.
  • Restringir a una bandeja de entrada (aparece cuando ya tienes bandejas de entrada): la única bandeja de entrada a la que se limita la clave.

Con la API:

curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "permission": "sending_access",
    "domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
  }'

La respuesta es { "id": "…", "token": "bs_…" }: el token aparece solo aquí. GET /api-keys lista las claves activas (nunca sus tokens) y DELETE /api-keys/{id} revoca una al instante; las solicitudes que la usan fallan de inmediato.

Permiso

Permiso Puede
Acceso total Usar todos los endpoints: envío, contactos, segmentos, temas, envíos masivos, dominios, webhooks, plantillas, correo recibido y claves de API. Una clave limitada a un dominio alcanza solo una parte de todo eso.
Solo envío Enviar emails (POST /emails, POST /emails/batch) y nada más. Todo lo que no sea enviar, y cualquier lectura del correo guardado, responde 403 restricted_api_key.

Usa una clave de solo envío en la aplicación que envía email transaccional. Si se filtra una clave de solo envío, no puede leer tus contactos, cambiar tus dominios ni crear otras claves.

Limitar una clave a un dominio

Una clave limitada a un dominio funciona dentro de ese dominio y no alcanza nada que pertenezca a todo el equipo. El dominio debe estar verificado antes de limitar una clave a él; no se puede usar el subdominio de bandeja de entrada compartido.

Qué Qué puede hacer la clave
Envío, emails, correo recibido, bandejas de entrada, bajas, envíos masivos Solo lo de ese dominio. Una solicitud sobre otro dominio responde 403 restricted_api_key.
GET /emails/metrics Lee solo las cifras de ese dominio; indicar otro dominio en domain_id responde 403 restricted_api_key.
GET /domains y /domains/{id} (leer, cambiar, eliminar, verificar) Lista y toca solo su propio dominio. Cualquier otro dominio, incluido el subdominio compartido, responde 404.
/api-keys POST crea claves limitadas al mismo dominio. GET lista, y DELETE revoca, solo las claves limitadas a ese dominio; cualquier otra clave responde 404.
Contactos, segmentos, temas Permitido. Los contactos son la libreta de direcciones compartida del equipo, pero la clave no puede levantar una baja de todo el equipo. Un segmento o tema que cree queda ligado a su propio dominio, y no puede desligar ninguno.
Webhooks (todos los métodos, incluido el secreto de firma), supresiones, plantillas, propiedades de contacto, GET /usage, GET /deliverability, verificaciones y POST /domains 403 restricted_api_key: pertenecen a todo el equipo.

Úsala en un servicio que pertenece a una sola marca: si se filtra, alcanza el dominio de esa marca y nada más, ni tus webhooks, ni tus otras claves, ni tus otros dominios.

Limitar una clave a una bandeja de entrada

Una clave de bandeja de entrada da a un agente de IA acceso a una sola bandeja de entrada y a nada más. Necesita acceso total, no puede limitarse también a un dominio, solo puede leer, responder, reenviar y enviar borradores de esa bandeja, y solo puede enviar desde su dirección. Deja de funcionar cuando la bandeja caduca o se elimina.

Límites

Límite Valor
Claves activas por equipo 25, incluidas las credenciales SMTP. Revoca una para crear otra (si no, 422).
Claves activas por bandeja de entrada 5, fuera de las 25 del equipo.
Solicitudes 600 por minuto por clave y 3000 por equipo; consulta los conceptos básicos de la API.

Quién puede crear cada clave

  • En el panel, crean claves los propietarios, los administradores y los desarrolladores.
  • Una clave que creas con la API nunca es más amplia que la clave que la creó: una clave de solo envío solo puede crear claves de solo envío, una clave limitada a un dominio solo puede crear claves para ese dominio (y solo ve y revoca esas), y una clave de bandeja de entrada no puede crear claves.
  • Una clave actúa con el rol de equipo que tiene hoy su creador, comprobado en cada solicitud. El creador es la persona que la hizo en el panel (o que conectó la aplicación que la hizo); una clave creada con la API lleva al creador de la clave que la creó. El rol no limita el trabajo diario: una clave de acceso total envía y gestiona contactos, envíos masivos, dominios, webhooks y claves sea cual sea el rol de su creador (una clave limitada a un dominio es la excepción, véase arriba). Las acciones de alto riesgo (borrar a un destinatario, quitar una supresión, deshacer una baja) exigen una clave cuyo creador sea hoy propietario o administrador; las demás claves responden 403 forbidden. Si el creador pierde rango, sus claves siguen el nuevo rol desde la siguiente solicitud. Si lo eliminan del equipo o se va, todas las claves de API que creó, las claves que esas claves crearon y sus claves de agente dejan de funcionar al instante (401 invalid_api_key) y aparecen como revocadas; volver a invitarlo no las recupera. Consulta los roles del equipo.

Crear, renombrar y revocar una clave queda registrado en el registro de auditoría.

Otras claves

  • Las credenciales SMTP son claves de solo envío que se crean en la página SMTP para el SMTP relay.
  • Las claves de agente (bs_agent_…) son solo para el servidor MCP. Se crean en MCP, se limitan a solo lectura, lectura y respuesta, o lectura y envío, y un equipo puede tener hasta 20. Tus claves de API normales no funcionan en el servidor MCP.

¿Te ha resultado útil esta página?