Copy page

Plataforma

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 y habilitar 2FA:

1. Inicia sesión en el Dashboard de Fluxis:
   • Staging: https://dashboard.stgfluxis.us
   • Production: 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.

Siguiente: intercambia la clave y el secreto por un token Bearer — consulta Guía de integración API — Autenticación.

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

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:

Code
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:

Code
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"

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

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

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 — crear cuenta y habilitar 2FA
• Autenticación de dos factores — requerida para crear claves
• Equipo y roles — quién puede gestionar claves API
• Guía de integración API — integración de extremo a extremo