Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

Autenticación

HTTP Basic Auth para la API de Fuxam v4 — clientId y clientSecret, ciclo de vida de credenciales, acceso todo o nada y buenas prácticas de seguridad.

Cada solicitud a la API de Fuxam v4 se autentica con HTTP Basic Auth usando el clientId y el clientSecret de una integración. En v4 no hay cookie de sesión separada, token portador OAuth ni encabezado de clave API por solicitud: el encabezado Authorization es toda la superficie de autenticación.

Por qué importa

Las credenciales de la API son poder a nivel de institución. Un clientSecret filtrado permite a un atacante leer y modificar los mismos datos que su integración, porque v4 no implementa ámbitos de permisos en Basic Auth. Una higiene sólida de credenciales — creación, almacenamiento, rotación y mínima exposición — es tan importante como el código de solicitud correcto.

Cómo encaja

La autenticación se relaciona con el producto de la siguiente manera:

  • Las credenciales se crean en Organization → API integrations en Fuxam Web.
  • La integración actúa en nombre de la institución, no como un usuario del personal con nombre en User Management.
  • Tras una autenticación exitosa, cada solicitud sigue las convenciones compartidas en la descripción general (sobre, paginación, errores).

Conceptos clave

Término Definición
Integration Cliente API registrado para su institución.
clientId Identificador público de la integración (el «nombre de usuario» de Basic Auth).
clientSecret Secreto confidencial (la «contraseña» de Basic Auth).
Basic Auth Encabezado estándar Authorization: Basic con clientId:clientSecret codificado en Base64.
All-or-nothing v4 no implementa ámbitos de permisos de clave API: las integraciones autenticadas tienen acceso completo de integración.

Cómo funciona Basic Auth

Codifique las credenciales en Base64 de la cadena clientId:clientSecret (sin espacios adicionales):

Authorization: Basic <base64(clientId:clientSecret)>

Ejemplo con curl (preferido: permite que curl codifique por usted):

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=1"

Codificación manual para depuración:

printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n'

Cómo obtener credenciales

Inicie sesión en Fuxam Web con una cuenta que pueda gestionar los ajustes de la organización.

Vaya a Organization → API integrations.

Cree una nueva integración y copie el clientId y el clientSecret en su almacén de secretos.

Verifique con una lectura simple como GET /users?limit=1 antes de conectar las credenciales a trabajos de producción.

Para un recorrido completo de la primera llamada, consulte Primeros pasos.

Acceso todo o nada

Los ámbitos de permisos de clave API no están implementados en v4. Basic Auth es todo o nada para la integración:

  • No hay forma documentada de emitir una clave API de «solo lectura» mediante ámbitos.
  • Trate cada integración como capaz de cualquier operación que la API exponga a las integraciones.
  • Reduzca el riesgo limitando quién puede crear integraciones, aislando credenciales por sistema y escribiendo clientes que solo invoquen los endpoints que necesitan.

Rotación y sustitución de credenciales

Planifique la rotación igual que con contraseñas de base de datos:

  1. Cree una integración nueva (o obtenga un secreto nuevo, si su proceso sustituye el secreto en la misma integración).
  2. Actualice cada consumidor (CI, middleware, entorno serverless) con las nuevas credenciales.
  3. Confirme que el tráfico de producción funciona con el nuevo par.
  4. Retire o elimine las credenciales antiguas para que ya no puedan autenticarse.

Buenas prácticas de seguridad

Práctica Orientación
Secret storage Mantenga clientSecret en un gestor de secretos o almacén de entorno cifrado. Nunca lo confirme en git ni lo pegue en tickets.
Least privilege (operational) Aunque no haya ámbitos de API, otorgue credenciales solo a los servicios que las necesiten; separe integraciones por carga de trabajo.
TLS only Llame exclusivamente a https://fuxam.app. Rechace redirecciones a URL sin TLS en clientes HTTP.
Log carefully Registre meta.requestId y códigos de estado; nunca registre el encabezado Authorization ni el secreto en bruto.
Rotate on staff change Cuando alguien con acceso al secreto se vaya, rote las credenciales.
Revoke on leak Si un secreto pudo haberse expuesto, deshabilite o sustituya la integración de inmediato y audite el tráfico reciente.

Errores frecuentes

Error Qué ocurre Solución
Base64 manual con saltos de línea 401 intermitente Elimine saltos de línea o use -u / Basic Auth de la biblioteca
Secretos incrustados en apps móviles o del navegador Cualquiera puede extraerlos Llame a la API solo desde componentes de servidor de confianza
Una integración compartida entre muchos equipos Rotación difícil; límites de tasa ruidosos Separe por sistema
Asumir 403 para recursos no autorizados v4 nunca emite 403 por denegación entre inquilinos Espere 404 resource_not_found — consulte Errores e idempotencia

Preguntas frecuentes

¿Hay OAuth2 o tokens de acceso personal en v4?

Este manual documenta HTTP Basic Auth con clientId y clientSecret de integración como método de autenticación de v4. Use ese patrón salvo que su institución reciba instrucciones distintas.

¿Cada usuario del personal necesita sus propias credenciales de API?

No. Las integraciones autentican la integración de la institución, no una cuenta individual de User Management. El personal sigue usando Fuxam Web con sus propios roles; el middleware usa las credenciales de la integración.

¿Qué código de estado indica credenciales incorrectas?

La autenticación fallida suele devolver 401. Distinguir «contraseña incorrecta» de «cliente desconocido» no es algo en lo que los clientes deban confiar más allá de tratar 401 como «corrija las credenciales».

Páginas relacionadas

¿Te ha resultado útil esta página?