#Claves de API pública

La pantalla Administración → Claves de API permite crear y administrar las integraciones que acceden a la API pública.

#Cliente, credencial y API key

Un cliente de API representa una integración, por ejemplo un ERP o un proceso de sincronización. En el cliente se definen el nombre, el estado y los permisos.

Cada cliente puede tener una o varias credenciales. Una credencial tiene un nombre para identificar dónde se usa, una fecha de caducidad opcional y una API key completa. La API key empieza por trowel_live_ y se usa para obtener tokens temporales.

No hay un secreto separado. Trowel muestra la API key completa una sola vez al crear o rotar la credencial. Cópiala en ese momento y guárdala en el gestor de secretos de la integración.

#Crear un cliente y su primera credencial

1. Abre Administración → Claves de API y pulsa Nuevo.
2. Escribe un nombre que identifique la integración.
3. Elige los permisos globales o por funcionalidad.
4. Indica un nombre para la primera credencial, por ejemplo ERP producción.
5. Si procede, fija su fecha de caducidad.
6. Guarda el cliente y copia la API key que se muestra.

Si cierras el aviso sin copiar la API key, no se puede volver a consultar. Crea otra credencial o rota la anterior.

#Administrar credenciales

Al editar un cliente puedes:

• Crear una credencial adicional para otro sistema o entorno sin compartir la misma API key.
• Rotar una credencial y mantener la anterior durante un periodo de solape. La nueva API key se muestra una sola vez.
• Revocar una credencial para impedir que vuelva a obtener tokens.
• Mostrar credenciales inactivas para consultar el historial de rotaciones y revocaciones.

Cada fila indica si la credencial es actual, anterior durante un solape o inactiva. También muestra la caducidad y la fecha de la última autenticación correcta. Esto permite comprobar si una integración ya usa la nueva API key antes de terminar una rotación.

Para rotar sin interrumpir el servicio:

1. Rota la credencial y define el tiempo de solape.
2. Copia la nueva API key y actualiza la integración.
3. Comprueba que aparece una autenticación correcta con la nueva credencial.
4. Deja que termine el solape o revoca la credencial anterior.

Desde el menú de acciones del listado puedes desactivar el cliente. Al hacerlo dejan de funcionar todas sus credenciales. Reactívalo desde el mismo menú cuando sea necesario.

#Permisos

Al crear o editar un cliente, la sección Ámbitos ofrece dos formas de asignar permisos:

• Global: permite elegir Sin acceso, Lectura o Lectura y escritura para el conjunto de la API pública. El acceso global incluye también los ámbitos compatibles que se incorporen más adelante.
• Por funcionalidad: permite conceder solo los permisos que necesita la integración.

#Permisos por funcionalidad

En escritorio, el selector aparece alineado a la izquierda y usa filas compactas. Cada recurso y sus permisos permanecen en una sola fila. En pantallas pequeñas o al usar un dispositivo táctil, los controles aumentan de tamaño y el selector se adapta al ancho disponible para que puedas revisar y seleccionar los permisos sin recortes ni desplazamiento horizontal.

El catálogo está dividido en seis áreas, en el mismo orden que el menú de Trowel:

• Proyectos: lectura y escritura.

• Repasos: lectura y escritura.

• Partes de trabajo: lectura, escritura y lectura de costes.

• Empresas

  • Clientes: lectura y escritura.
  • Proveedores: lectura y escritura.

• Productos

  • Productos: lectura y escritura.
  • Precios: lectura y escritura.
  • Cambios: lectura.

• Series: lectura.

Cada permiso se selecciona de forma independiente. Por ejemplo, una integración puede consultar partes de trabajo sin recibir sus costes, o consultar proyectos sin poder modificarlos.

El resumen situado a la derecha muestra los permisos seleccionados antes de guardar. Si estás revisando un cliente existente, aparecen también los permisos que ya tenía asignados en cualquiera de las seis áreas.

Los usuarios con permiso de consulta pueden ver los ámbitos seleccionados, pero el selector permanece en modo de solo lectura. Para cambiarlos, administrar credenciales o activar y desactivar clientes hace falta el permiso de edición de claves de API.

La guía API pública de Trowel explica cómo usar la API key y trabajar con el portal de desarrolladores.