# Autenticación del API Bancario

> Login, intercambio de token y uso del Bearer JWT en el API Bancario de Tilopay.

- kind: concept
- status: stable
- api_version: 1.0.0
- last_verified: 2026-09-02
- url: https://www.tilopay.com/developers/api-bancario/autenticacion

El API Bancario usa un flujo de dos pasos: primero autenticás al cliente con correo y
contraseña, después intercambiás el token resultante por un access token JWT que firma
todas las demás llamadas.

Los tres endpoints del grupo `Auth` son los únicos que **no** llevan `Authorization`.
Todo el resto del API exige `Authorization: Bearer <access_token>`.

## Paso 1 — Login [#login]

```http
POST /api/public/v1/auth/login
```

Cuerpo requerido: `email` (formato email) y `password`.

```json
{
  "email": "operaciones@comercio.com",
  "password": "••••••••"
}
```

La respuesta `200` devuelve en `data`:

| Campo | Tipo | Descripción |
|---|---|---|
| `gidp_id_token` | string | Token de identidad para el paso 2. |
| `assignments` | array | Contextos disponibles del cliente. |

Cada elemento de `assignments` trae `assignment_id`, `owner_type`, `owner_id`,
`tenant_id`, `tenant_code`, `country_code`, `role`, `roles` y `status`. Elegí el
`assignment_id` del contexto con el que vas a operar.

## Paso 2 — Intercambio de token [#exchange]

```http
POST /api/public/v1/auth/token/exchange
```

Cuerpo requerido: `gidp_id_token` (el del paso 1) y `assignment_id` (el contexto
elegido).

```json
{
  "gidp_id_token": "eyJhbGciOi...",
  "assignment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

La respuesta `200` devuelve en `data`:

| Campo | Tipo | Descripción |
|---|---|---|
| `token` | string | Access token JWT. |
| `expires_in` | integer | Vigencia del token en segundos. |
| `claims` | object | Contexto resuelto del token. |

`claims` incluye `sub`, `subject_kind`, `user_type`, `tenant_id`, `owner_type`,
`owner_id`, `roles`, `scopes`, `country_code`, `locale`, `channel`, `idp`, `idp_sub` e
`idempotency_key`.

## Paso 3 — Usar el Bearer [#bearer]

El esquema de seguridad declarado es `BearerAuth`: HTTP bearer con formato JWT.

```http
Authorization: Bearer <access_token>
```

El contexto viaja **dentro** del token: no se envían `tenant_id`, `owner_id` ni
`owner_type` como parámetros en las operaciones de negocio. El token acota por sí solo a
qué cuentas y pagos podés acceder.

Cuando el token está ausente, vencido o es inválido, la respuesta es `401` con
`response_code: UNAUTHORIZED`. Si el token es válido pero el contexto no autoriza el
recurso, es `403` con `FORBIDDEN`. Repetí el paso 2 para renovar el access token antes de
que se cumpla `expires_in`.

## Contraseñas [#password]

```http
POST /api/public/v1/auth/request-set-password
```

Inicia el proceso de establecer o restablecer la contraseña del correo indicado. No
requiere autenticación previa y responde siempre igual, exista o no la cuenta, para no
revelar si un correo está registrado.

```json
{
  "email": "operaciones@comercio.com"
}
```