Crear y gestionar tokens de API

Los tokens de API controlan lo que una aplicación o un agente puede hacer en tu cuenta. Cada token tiene un nombre, permisos, restricciones de dominio opcionales y una fecha de caducidad.

¿Vas a conectar un cliente MCP? Si admite autorización en el navegador, añade https://trekmail.net/mcp como servidor MCP remoto y aprueba el acceso en el navegador. Normalmente no necesitas crear ni pegar un token. Los tokens tm_live_ manuales son para scripts, tareas de CI, MCP autoalojado y clientes que no admiten ese flujo. Consulta Conectar agentes de IA (MCP).

Antes de empezar

• Todos los planes pueden crear tokens de API, incluido Nano. Los planes Nano se limitan a los permisos de Email Verifier (verify:read, verify:write).
• Los planes Starter permiten permisos de infraestructura de solo lectura, además de todos los permisos de Drive y Email Verifier. Starter también puede gestionar el reenvío en el panel, pero el acceso de escritura para el reenvío mediante API (mailboxes:forwarding:write) requiere Pro o Agency. Pro y Agency habilitan todos los permisos.
• El propietario puede gestionar todas las credenciales de la cuenta. Un miembro delegado con permiso para tokens de API solo puede gestionar las credenciales que haya creado y solo puede conceder los permisos y dominios que ya formen parte de su membresía.
• Consejo: Haz clic en Iniciar recorrido en la página Agentes de IA y API para ver una breve guía sobre las opciones de conexión, los tokens, las aplicaciones conectadas y el registro de auditoría.

Crear un token de automatización de Drive

La API de Drive y las herramientas MCP usan tokens de operaciones (tm_live_...). Selecciona únicamente los permisos de Drive que necesite el flujo de trabajo:

• Informes de solo lectura: drive:account:read, drive:mailbox:read o drive:addon:read.
• Automatización de cargas: añade drive:account:write o drive:mailbox:write.
• Enlaces públicos de entrega: añade drive:account:share o drive:mailbox:share.
• Limpieza permanente: usa drive:account:purge o drive:mailbox:purge únicamente en un token separado y estrictamente controlado.

La compra, el cambio de tamaño y la cancelación del complemento Drive no están disponibles mediante tokens de API. Los agentes pueden consultar el estado y el precio del complemento con drive:addon:read, pero los cambios de suscripción permanecen en el panel.

Crear un token de automatización de White Label

White Label utiliza cinco permisos de token de operaciones: branding:read, branding:write, members:read, members:write y activity:read. Solo aparecen mientras la cuenta tiene acceso a White Label. members:write está marcado como peligroso porque puede retirar el acceso y revocar las claves de otra persona.

Para una integración de estado y auditoría de solo lectura, selecciona branding:read, members:read y activity:read. Añade branding:write solo para configurar la marca y DNS. Añade members:write únicamente cuando la automatización deba invitar o modificar personas.

Durante el periodo de gracia de cancelación, el propietario conserva los tres permisos de lectura para la recuperación, mientras que las operaciones de escritura y las credenciales delegadas de White Label dejan de funcionar. La reactivación no recupera una credencial revocada; crea o autoriza una nueva.

Crear un token

1. Ve a Agentes de IA y API → Tokens.
2. Haz clic en Crear token.
3. Completa el formulario:
   • Nombre: Una etiqueta para identificar el token (por ejemplo, "Agente Claude", "Canalización CI/CD").
   • Caducidad: Elige 7 días, 30 días, 90 días, una fecha personalizada o nunca.
   • Permisos: Selecciona las operaciones que puede realizar el token. Todos los permisos disponibles están marcados de forma predeterminada.
   • Restricción de dominio: Elige "Todos los dominios" o selecciona dominios concretos para limitar el acceso del token.
4. Haz clic en Crear token.

Después de crearlo, el token en texto sin formato se muestra una sola vez. Cópialo inmediatamente o usa el botón Descargar para guardarlo como archivo .txt.

El token no se puede volver a consultar. Guárdalo de forma segura antes de cerrar la confirmación.

Crear un token de mensajes

Los tokens de mensajes permiten que los agentes lean y envíen correo desde un buzón específico. Son independientes de los tokens de operaciones y se crean mediante programación a través de la API usando tu token de operaciones.

Para crear un token de mensajes, el agente llama a:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Elige los permisos mínimos que necesite el flujo de trabajo:

El token en texto sin formato (tm_msg_...) se devuelve una sola vez. Añádelo a tu configuración MCP como TREKMAIL_MESSAGE_TOKEN.

Los tokens de mensajes están disponibles en los planes Pro y Agency. El token de operaciones debe tener el permiso mailboxes:message-tokens:manage.

Para una cuenta de Gmail conectada u otra bandeja externa, usa external_account_id. Para que los destinatarios vean en su lugar una dirección empresarial autorizada, usa también un identity_id devuelto por el endpoint de identidades. Consulta Direcciones Enviar como mediante API y MCP.

Formato del token

TrekMail usa dos prefijos para distinguir los tipos de token:

Los primeros 8 caracteres después del prefijo se guardan como prefijo visible en el panel para facilitar la identificación.

Permisos

Los permisos controlan lo que puede hacer el token. Las opciones disponibles dependen de tu plan:

• Nano: Solo Email Verifier (verify:read, verify:write). Añadir Drive Storage también proporciona a la cuenta las funciones de la API de Drive y MCP a las que tiene derecho.
• Starter: Acceso completo a Drive y Email Verifier, y acceso de solo lectura al resto (dominios, buzones, reenvío, filtros de correo, respuesta automática, migraciones, tickets, SMTP y Cloudflare). Usa el panel para las acciones de escritura que Starter no ofrece mediante la API, como crear migraciones, responder a tickets o cambiar la respuesta automática.
• Pro y Agency: Acceso completo. Lectura, escritura, creación y eliminación en todas las familias, además de tokens de mensajes para leer y enviar correo mediante la API.

Los permisos de White Label son un derecho del complemento, no un atajo en la tabla de planes. Solo se ofrecen mientras White Label está activo; el propietario conserva acceso de recuperación de solo lectura durante el periodo de gracia de cancelación.

Consulta Permisos de API y planes para ver la referencia de cada permiso.

Restricciones de dominio

De forma predeterminada, los tokens pueden acceder a todos los dominios de tu cuenta. Para limitar un token a dominios concretos:

1. Selecciona Dominios seleccionados en la sección de restricción de dominio.
2. Marca los dominios a los que debe acceder el token.

Un token restringido recibe respuestas 404 al intentar acceder a recursos de otros dominios; la API se comporta como si esos dominios no existieran.

Revocar un token

1. Ve a Agentes de IA y API → Tokens.
2. Busca el token en la lista.
3. Haz clic en Revocar.
4. Confirma la revocación.

Los tokens revocados dejan de funcionar inmediatamente. Cualquier solicitud de API que use uno recibe 401 Unauthorized.

La revocación es permanente y no se puede deshacer. Crea un token nuevo si necesitas restaurar el acceso.

Estado del token

Los tokens tienen tres estados:

Usa el filtro de estado de la página Tokens para ver los tokens por estado.

Registro de auditoría

Cada creación y revocación de un token aparece en la pestaña Registro de auditoría. Los eventos incluyen el nombre del token, la acción y la hora.

Soluciones rápidas

• "Permisos no disponibles en tu plan": Tu plan no incluye esos permisos. Nano se limita a verify:read y verify:write (añade el complemento Drive Storage para obtener también los permisos drive:*). Starter añade acceso de lectura a todas las familias de infraestructura, además de Drive y Email Verifier completos. Pro y Agency habilitan la escritura en todas partes.
• Has perdido el token en texto sin formato: El token no se puede recuperar. Revócalo y crea uno nuevo.
• El token funciona, pero devuelve 404 para algunos dominios: Probablemente tenga una restricción de dominio. Revócalo y vuelve a crearlo con "Todos los dominios", o añade los dominios que faltan a la restricción.
• El permiso de White Label devuelve scope_blocked_by_entitlement: Reactiva White Label y crea o autoriza una credencial con el permiso necesario.
• Un token delegado dejó de funcionar tras cambiar un rol: Reducir, suspender o eliminar el acceso de un miembro revoca inmediatamente las credenciales afectadas. Crea un token nuevo cuando el propietario restaure el acceso correcto.