Authentication & Login

Todas las APIs de API Broker utilizan autenticación basada en tokens Bearer (JWT) gestionados a través de AWS Cognito. Cada request a la API debe incluir un token válido en el header de autorización. Sin él, la API devuelve 401 Unauthorized.

Proceso de autenticación

Paso 1 — Login

El primer paso es obtener un token realizando una llamada al endpoint de login con las credenciales asignadas por API Broker.

POST /api/auth/login

Request body:

{
  "username": "tu_usuario",
  "password": "tu_password"
}

Response:

{
  "AccessToken": "eyJraWQiOiJ...",
  "ExpiresIn": 3600,
  "TokenType": "Bearer",
  "RefreshToken": "eyJjdHkiOiJ...",
  "IdToken": "eyJraWQiOiJ..."
}

Guardá el AccessToken y el RefreshToken. El primero se usa en cada request; el segundo permite renovar la sesión cuando el AccessToken expira sin pedir contraseña nuevamente.

Paso 2 — Usar el token en cada request

Todos los endpoints de la API requieren el AccessToken en el header Authorization:

Authorization: Bearer {AccessToken}

Ejemplo:

curl -X GET https://apibroker.prd-adcap.com/api/accounts/persons?person_id=F-9686d35b \
  -H "Authorization: Bearer eyJraWQiOiJ..."

En code:

const response = await fetch('https://apibroker.prd-adcap.com/api/accounts/persons', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

Paso 3 — Renovar el token

El AccessToken expira a los 3600 segundos (1 hora). Cuando eso ocurre, la API devuelve 401 Unauthorized. Para evitar interrumpir la operatoria, hay dos opciones:

Opción A — Volver a hacer login (más simple)

Realizar nuevamente el POST /api/login con usuario y contraseña. Obtenés un nuevo AccessToken fresco.

Opción B — Usar el Refresh Token (recomendado para integraciones productivas)

El RefreshToken tiene una vida útil más larga y permite obtener un nuevo AccessToken sin exponer las credenciales en cada solicitud. Esto es ideal para sistemas que corren de forma continua.

Credenciales

Las credenciales de acceso (username y password) son asignadas por el equipo de API Broker durante el proceso de integración, en la etapa de Credenciales de Staging y posteriormente en Credenciales de Producción.

Si necesitás credenciales o resets de acceso, contactá a tu oficial de cuenta o escribí a [email protected].

Buenas prácticas de seguridad:

• Nunca incluyas las credenciales directamente en el código fuente.
• Guardálas como variables de entorno o en un gestor de secretos.
• No compartirlas entre equipos sin autorización.
• Rotalás periódicamente o ante cualquier sospecha de compromiso.

Códigos de respuesta relacionados con autenticación

Implementación recomendada

Para integraciones productivas, la práctica recomendada es:

1. Al iniciar la aplicación, realizar el login y almacenar el AccessToken y el RefreshToken en memoria (nunca en storage pública).
2. En cada request, adjuntar el AccessToken en el header Authorization.
3. Al recibir un 401, intentar renovar el token automáticamente usando el RefreshToken antes de propagar el error al usuario.
4. Si el refresh también falla, iniciar un nuevo login con credenciales.

Esto garantiza una experiencia continua sin interrupciones por expiración de sesión.

Puntos clave para recordar

1. Todo request necesita Authorization: Bearer {AccessToken} — sin excepción.
2. El token expira en 1 hora. Implementá renovación automática en producción.
3. Las credenciales son por ambiente. STG y PRD tienen usuarios separados.
4. 401 = token expirado o ausente. 403 = permisos insuficientes. Son errores diferentes.
5. Nunca hardcodees credenciales en el código fuente o repositorios.
6. Las credenciales las asigna API Broker durante el proceso de integración. No se autogestionan.