NuevoVer cómo
FirstSales
Inicio/Tutoriales/Cómo crear y gestionar claves de API de desarrollador en FirstSales
Desarrollador y CLI

Cómo crear y gestionar claves de API de desarrollador en FirstSales

Genera claves de API de mínimo privilegio con alcances por recurso, úsalas con la CLI y la API REST, y rótalas o revócalas de forma segura sin causar una interrupción.

7 min de lectura·Intermedio·6 pasos
  1. 1

    Abre Settings → API

    Las claves de API viven en Settings → API. Aquí es donde generas la credencial que autentica el CLI y cualquier llamada directa a https://api.app.firstsales.io. Necesitas el permiso adecuado para ver esta pestaña.

  2. 2

    Crea una clave con permisos mínimos necesarios

    Haz clic para crear una clave, dale un name (algo que indique dónde se usa, por ejemplo "ci-contact-sync"), y marca únicamente los scopes que necesita. Los scopes son por recurso y se dividen entre lectura y escritura, por ejemplo contacts:read, contacts:write, campaigns:read, kb:read. Existe un scope * que otorga todo; evítalo salvo que realmente necesites acceso total.

    Crea una clave con permisos mínimos necesarios
  3. 3

    Copia la clave de inmediato

    La clave completa se muestra exactamente una vez: "Copy this key now. It will not be shown again." Cópiala directamente en tu gestor de secretos o de contraseñas. Si la pierdes, no se puede recuperar; tendrás que revocarla y crear una nueva. Nunca la pegues en código, un chat o un commit.

  4. 4

    Úsala con el CLI

    Exporta la clave como FIRSTSALES_API_KEY y el CLI la detecta automáticamente. Verifica con whoami antes de hacer cualquier otra cosa:

    export FIRSTSALES_API_KEY="fs_live_..."   # from your secret store, never hardcoded
firstsales whoami --json
  5. 5

    Úsala directamente con la API

    Para HTTP puro, envía la clave como un token Bearer. Empieza con whoami para confirmar que la clave resuelve correctamente y ver a qué org/workspace tiene acceso:

    curl -s https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  6. 6

    Rota y revoca

    Cada clave de la lista se puede revocar, y la revocación es inmediata y sin deshacer: cualquier CLI o servicio que la use fallará en la siguiente llamada. Para rotar: crea la nueva clave, despliégala en tu gestor de secretos, confirma que la nueva funciona y luego revoca la antigua. Revoca al instante si alguna vez se expone una clave.

Consejos de experto

Atajos aprendidos a fuerza de experiencia para mantener el precalentamiento en curso.

1

Una clave por consumidor

Dale a CI, a tu laptop y a cada integración su propia clave nombrada. Cuando una se filtra o un servicio se retira, revocas solo esa clave en lugar de romperlo todo.

2

El mínimo privilegio gana a la comodidad

Una sincronización de solo lectura no necesita contacts:write, y casi nada necesita `*`. Limita los scopes: una clave de solo lectura filtrada no puede modificar tus datos.

3

Cópiala una vez, guárdala en un gestor de secretos

La clave se muestra una única vez. Pégala directamente en tu gestor de secretos de CI o de contraseñas, nunca en el código fuente, un .env que puedas commitear, ni en un mensaje de chat.

4

Rota con solapamiento, no con vacío

Crea, despliega, verifica y luego revoca. Revocar antes de que el reemplazo esté activo causa una interrupción; la ventana de solapamiento mantiene las llamadas funcionando durante la rotación.

Preguntas frecuentes

¿Dónde creo una clave de API?

Settings → API. Dale un nombre, marca los scopes que necesita y créala. La clave autentica tanto el CLI como las llamadas directas a la API.

¿Qué son los scopes?

Permisos por recurso, divididos entre lectura y escritura, por ejemplo contacts:read, campaigns:write, kb:read, además de un * que otorga todo. Marca solo lo que necesite el consumidor de la clave.

Perdí mi clave, ¿puedo volver a verla?

No. La clave completa se muestra una vez al crearla (“It will not be shown again”). Si la pierdes, revoca esa clave y crea una nueva.

¿Cómo usa el CLI la clave?

Configúrala como la variable de entorno FIRSTSALES_API_KEY; el CLI la lee automáticamente. Ejecuta firstsales whoami para confirmar que funciona.

¿Cómo revoco una clave?

En la lista de configuración de la API, revócala. La revocación es inmediata y permanente: cualquier cosa que use esa clave fallará en su siguiente llamada, así que rota primero un reemplazo.

¿Cómo debo rotar claves de forma segura?

Crea la nueva clave, despliégala, confirma que funciona y luego revoca la antigua. Este solapamiento evita una interrupción. Revoca de inmediato (sin solapamiento) solo si una clave queda expuesta.

¿Listo para ponerlo en práctica?

Comienza tu prueba de FirstSales y lanza un buzón precalentado y autenticado en minutos.

Empieza por $1
Todos los tutoriales