Claves de API

Una clave de API permite que un script (o un agente) haga por HTTP lo que una persona hace en la interfaz. La creas desde tu cuenta, y se muestra una sola vez: cópiala entonces, o crea otra.

Qué abre una clave

Una clave pertenece a una organización, y esa organización es todo su mundo. No puede ver ni tocar nada fuera de ella, y no existe ninguna clave que abarque dos. Y lo que es más importante, una clave no es una segunda identidad con poderes propios. Lleva los derechos del miembro que la creó: una clave creada por un administrador puede escribir, una clave creada por un miembro solo puede leer. Nada es accesible mediante la API que su creador no pudiera hacer a mano.
Una clave deja de funcionar cuando su propietario sale de la organización. Responde 401 desde ese momento, exactamente como si se hubiera revocado: ningún acceso huérfano sobrevive a una salida. Revocar la clave de un compañero que se fue es una tarea de orden, no una corrección de seguridad.

Cuánto dura

Cuando creas una clave eliges si termina: deja marcada Nunca expira y sigue siendo válida hasta que la revoques, o desmárcala y elige una fecha, entre un día y un año a partir de hoy. La columna Expira de la pantalla de claves API te dice cuál es cuál. Una vez pasada esa fecha, la clave responde 401, exactamente igual que una revocada.

Usar una

Cada solicitud la lleva en la cabecera x-api-key:
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/tags"
Una sola llamada le dice a una clave dónde está: qué organización abre, con qué rol y qué listas existen detrás. Ese es todo el arranque: consulta Discovery.

Buenas prácticas

  • Una clave por uso. Una clave por script, por agente, por entorno. Así, revocar una no le cuesta nada a las demás.
  • Nómbralas por lo que hacen, no por quién eres: el nombre es lo que leerás cuando decidas si revocarla.
  • Los contactos importados registran el nombre de la clave que los creó, así que una clave bien nombrada es también la forma de rastrear el origen de una audiencia meses después.

Qué implica en otras partes

Revocar una clave es inmediato e irreversible. Nada de lo que creó se deshace: los contactos, las plantillas y las campañas que hizo se quedan exactamente como están. La referencia completa (el formato de respuesta, los códigos de estado, quién puede llamar a qué) está en la sección de la API.