---
icon: key
title: Autenticación
description: 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

```mermaid
flowchart LR
  Admin[Administrador de organizacion] --> Create[Integraciones API]
  Create --> Creds[clientId y clientSecret]
  Creds --> Header[Authorization Basic]
  Header --> API[Fuxam API v4]
  API --> Data[Datos de institucion]
```

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](/docs/es/fuxam-web/base/user-management).
- Tras una autenticación exitosa, cada solicitud sigue las convenciones compartidas en la [descripción general](/docs/es/api/overview) (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):

```http
Authorization: Basic <base64(clientId:clientSecret)>
```

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

```bash
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:

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

:::note
Envíe siempre las credenciales por **TLS** (`https://`). Nunca envíe Basic Auth por HTTP sin cifrar.
:::

## Cómo obtener credenciales

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

2. Vaya a **Organization → API integrations**.

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

4. 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](/docs/es/api/getting-started).

## 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.

:::warning[No hay ámbitos en v4]
No asuma que un ámbito ausente bloqueará una escritura. Si su cliente puede autenticarse, aplique el principio de mínimo privilegio en **su** código y política de despliegue.
:::

## 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.

:::tip
Use **una integración por sistema consumidor** (por ejemplo, sincronización SIS frente a exportación BI). Así puede rotar o revocar un cliente sin interrumpir a los demás, y `meta.requestId` junto con los presupuestos de límite de tasa son más fáciles de atribuir.
:::

## 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](/docs/es/api/errors-and-idempotency) |

## 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

**[Primeros pasos](/docs/es/api/getting-started)**

Primera solicitud autenticada de principio a fin.

**[Errores e idempotencia](/docs/es/api/errors-and-idempotency)**

Detalles de problemas, 401 frente a 404 y límites de tasa.

**[Descripción general de la API](/docs/es/api/overview)**

Convenciones compartidas para cada endpoint.

**[Recetas](/docs/es/api/recipes)**

Patrones prácticos que asumen autenticación correcta.
