Las claves de API permiten que tu código y tu CI hagan preguntas y lean resultados. Para asistentes de IA como Claude o ChatGPT, conéctate con OAuth: no necesita clave.

Crear una clave

  1. Ve a Desarrolladores en el portal y elige Crear clave.
  2. Ponle el nombre del sitio donde se usará, por ejemplo «CI» o «bot de precios».
  3. Elige sus permisos y un tope de gasto diario.
  4. Confirma que eres tú. La clave empieza por fh_live_ y se muestra una sola vez: cópiala en tu almacén de secretos enseguida.

Solo guardamos un hash de la clave, así que no podemos volver a mostrarla. Si la pierdes, rótala.

Permisos

  • questions:read: resultados y listas.
  • questions:write: estimar, preguntar, cancelar, compartir, subir archivos.
  • templates:read: plantillas de precio fijo.
  • account:read: saldo y movimientos.
  • webhooks:read: ver los endpoints de webhook y sus entregas.
  • webhooks:write: añadir, cambiar, rotar el secreto, probar, reenviar y eliminar endpoints de webhook.
  • apps:read: ver los espacios de trabajo de Slack donde está 50heads, con el tope diario de cada uno.
  • apps:write: cambiar el tope diario de un espacio de trabajo de Slack, o quitarlo. Consulta Usar 50heads en Slack.
  • events:read: leer el flujo de eventos, para la exportación al almacén de datos y herramientas como Airbyte (se está activando poco a poco).

Para admins de una organización, donde tenga cuentas de servicio (se está introduciendo poco a poco):

  • organization:read: ver la organización, sus dominios, reglas de acceso, inicio de sesión único, SCIM y cuentas de servicio.
  • organization:write: cambiar dominios, reglas de acceso y ajustes de SCIM.
  • members:read: ver dónde tiene la sesión iniciada un miembro de la organización.
  • members:write: cerrar la sesión de un miembro en todas partes.
  • audit:read: leer y exportar el registro de auditoría.

Crea la clave con el equipo de la organización en uso. Los permisos de organización solo funcionan mientras seas admin de la organización: si dejas de serlo, la clave los pierde al momento. Algunas acciones siempre te necesitan a ti, con la sesión iniciada, tenga la clave los permisos que tenga: la conexión de inicio de sesión único y hacerlo obligatorio, los propietarios de emergencia, los tokens SCIM, cuánto tiempo se guardan los eventos de auditoría, las retenciones legales, ceder un equipo y las cuentas de servicio. Para un agente que deba seguir funcionando cuando alguien se va, usa una cuenta de servicio en vez de una clave.

Da a cada clave solo lo que necesita. Los permisos de webhook, de apps y de organización nunca vienen marcados. Consulta Webhooks.

Cambiar una clave

Elige Permisos y límites en una clave de Desarrolladores para cambiarle el nombre, los permisos, el tope diario, el tope por pregunta o las direcciones desde las que se puede usar. Quitar un permiso, cambiar el nombre y cambiar un tope surten efecto al momento. Añadir un permiso te pide confirmar antes que eres tú, igual que al crear una clave. Si usas la verificación en dos pasos, confirma con tu app de autenticación, una llave de acceso o un código de recuperación.

Claves de un equipo

Una clave creada mientras hay un equipo en uso gasta los créditos del equipo. El propietario y los administradores del equipo pueden verla, cambiar sus topes y revocarla. Consulta Tu equipo.

Rotar y revocar

Rotar crea un secreto nuevo para la misma clave y la misma configuración. El secreto antiguo sigue funcionando 24 horas, para que actualices tus scripts, y después deja de funcionar. Revocar desactiva la clave para siempre, en menos de un segundo.

Claves antiguas

Las claves creadas antes de que existieran los permisos solo pueden preguntar, leer resultados, usar plantillas y ver tu saldo, y no tienen tope diario. Ya no se pueden crear nuevas. Las que aún tengas aparecen en Desarrolladores en Claves antiguas, donde puedes revocarlas. Las retiraremos con 90 días de aviso por correo. Crea una clave nueva con permisos y un tope, pasa tu código a ella y revoca la antigua.

Mantén las claves en secreto

Las claves son para servidores. Las peticiones con una clave desde un navegador se rechazan, para que nadie pueda sacar una clave de una página web. Nunca subas claves a un repositorio.

Consulta la documentación para desarrolladores (en inglés) sobre autenticación, errores y límites de peticiones.