# Credenciales API

Las credenciales API autentican tu integración servidor a servidor con la REST API de Fluxis. Gestiónalas en el Dashboard de Fluxis en **`/app/api-keys`** (solo roles Owner y Admin).

## Resumen

Cada par de credenciales consta de:

| Componente | Descripción |
| --------- | ----------- |
| **API Key ID** | Identificador público enviado en cada solicitud protegida como `x-fluxis-api-key` |
| **API Secret** | Secreto privado usado solo para `POST /v1/auth/token` |

### Formato del Key ID

| Entorno | Prefijo | Ejemplo |
| ----------- | ------ | ------- |
| Development | `fxs.dev.` | `fxs.dev.a1b2c3d4-...` |
| Staging | `fxs.stg.` | `fxs.stg.a1b2c3d4-...` |
| Production | `fxs.prd.` | `fxs.prd.a1b2c3d4-...` |

El secreto se muestra **una vez** al crear una clave. Guárdalo de forma segura — no puedes recuperarlo de nuevo desde el dashboard.

## Crea tu primera clave API

Sigue estos pasos después de [registrarte](/es/docs/merchant-integration/sign-up) y [habilitar 2FA](/es/docs/developers/two-factor-auth):

1. Inicia sesión en el Dashboard de Fluxis:
   - Staging: [https://dashboard.stgfluxis.us](https://dashboard.stgfluxis.us)
   - Production: [https://dashboard.fluxis.us](https://dashboard.fluxis.us)
2. En la barra lateral, abre **Developers → API Keys** (ruta: `/app/api-keys`).
3. Haz clic para **crear una nueva clave**.
4. Asigna un nombre descriptivo (p. ej. `staging-backend-integration`).
5. Asigna los roles **`read`** y **`write`** para una integración de pagos estándar.
6. Completa el desafío de **verificación 2FA** cuando se solicite.
7. Copia el **API Secret** de inmediato y guárdalo en tu gestor de secretos — el dashboard no lo mostrará de nuevo.
8. Anota el **API Key ID** (`fxs.stg.*` o `fxs.prd.*`) para usarlo como `x-fluxis-api-key` en solicitudes protegidas.

::::warning
Solo los colaboradores **Owner** y **Admin** pueden crear claves API. Consulta [Equipo y roles](/es/docs/developers/team-and-roles) si necesitas acceso.
::::

Siguiente: intercambia la clave y el secreto por un token Bearer — consulta [Guía de integración API — Autenticación](/es/docs/developers/tutorials/api-integration-guide#paso-2--autenticacion).

## Acceso al dashboard

Abre el Dashboard de Fluxis y navega a:

**`/app/api-keys`**

Acciones disponibles (Owner / Admin):

| Acción | Descripción |
| ------ | ----------- |
| List keys | Vista paginada de claves API de la organización |
| Create key | Generar una nueva clave + secreto (requiere verificación 2FA) |
| Update name / roles | Cambiar nombre para mostrar o roles de permiso |
| Update allowed IPs | Restringir solicitudes a rangos IP específicos |
| Enable / Disable | Activar o desactivar clave sin eliminarla |
| Delete | Eliminar permanentemente una clave |

::::warning
Crear una nueva clave API requiere un desafío activo de **autenticación de dos factores**. Regístrate en [`/app/user/2fa`](/es/docs/developers/two-factor-auth) antes de crear tu primera clave.
::::

## Roles API

Cada clave tiene asignado uno o más roles API:

| Rol | Permisos típicos |
| ---- | ------------------- |
| `read` | Acceso de solo lectura (listar POS, obtener solicitudes de pago, listar transacciones) |
| `write` | Crear y modificar recursos (solicitudes de pago, reembolsos, webhooks) |

Los roles se almacenan en la credencial y los aplica la capa de autorización de la API. Las claves de alcance organizacional operan en todas las cuentas de tu organización; las claves de alcance de cuenta (cuando se provisionen) están limitadas a una sola cuenta.

## Flujo de autenticación

Las credenciales API **no** se envían en cada solicitud directamente. Intercámbialas por un token Bearer de corta duración:

```bash
curl -X POST "https://api.fluxis.us/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "fxs.prd.YOUR_KEY_ID",
    "api_secret": "YOUR_API_SECRET"
  }'
```

Luego llama endpoints protegidos con **ambos** encabezados:

```bash
curl "https://api.fluxis.us/v1/pos?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"
```

::::note
**No** envíes `x-fluxis-api-key` en `POST /v1/auth/token` — solo el cuerpo JSON con `api_key` y `api_secret`.
::::

### Duración del token

- Los tokens de acceso expiran después de **1 hora**
- Solicita un nuevo token antes de la expiración
- Deshabilitar una clave invalida su uso de inmediato

## Lista blanca de IP

Desde `/app/api-keys`, puedes restringir una clave a direcciones IP de origen o rangos CIDR específicos. Las solicitudes desde otras IP se rechazan incluso con un token válido.

Deja la lista blanca vacía para permitir cualquier IP (no recomendado para producción).

## Mejores prácticas de seguridad

::::warning
Nunca incorpores secretos API en código del lado del cliente, apps móviles o repositorios públicos. Las credenciales pertenecen solo a tu backend.
::::

1. **Usa claves separadas por entorno** — dev, staging y production nunca deben compartir credenciales
2. **Aplica mínimo privilegio** — prefiere claves `read` para servicios de informes; usa `write` solo donde sea necesario
3. **Deshabilita claves no usadas** — deshabilita o elimina claves que ya no necesites
4. **Habilita 2FA** — requerida para crear claves; protege el acceso al dashboard
5. **Monitorea `last_used_at`** — revisa la actividad de claves en la lista del dashboard

## Ciclo de vida de credenciales

| Evento | Efecto |
| ----- | ------ |
| Key created | Secreto mostrado una vez; clave habilitada por defecto |
| Key disabled | El intercambio de tokens y las llamadas API fallan |
| Key enabled | Operación normal reanudada |
| Key deleted | Permanente; crea una nueva clave para reemplazar |

::::info
La **rotación** de credenciales (reemplazar una clave manteniendo la misma identidad lógica) se gestiona a través del soporte de Fluxis o creando una nueva clave, migrando integraciones y eliminando la antigua. No hay API pública de "rotar secreto in situ" hoy.
::::

## Lo que las credenciales no pueden hacer

- Inicio de sesión en el dashboard (los colaboradores usan email/contraseña + 2FA, no claves API)
- Recuperación automática del secreto después de la creación

## Documentación relacionada

- [Registro de comercio](/es/docs/merchant-integration/sign-up) — crear cuenta y habilitar 2FA
- [Autenticación de dos factores](/es/docs/developers/two-factor-auth) — requerida para crear claves
- [Equipo y roles](/es/docs/developers/team-and-roles) — quién puede gestionar claves API
- [Guía de integración API](/es/docs/developers/tutorials/api-integration-guide) — integración de extremo a extremo