---
title: "Usuarios y autenticación de sesión"
description: "Login, refresh con rotación, logout, /me y gestión de usuarios (roles client/admin)."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.pagofast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usuarios y autenticación de sesión

# Usuarios

La API distingue autenticación de **usuario** (JWT + refresh) para management — y también para rutas de negocio cuando el OpenAPI lo admite — de la autenticación con **API key**.

## Endpoints

```http
POST /v1/auth/login
POST /v1/auth/refresh
POST /v1/auth/logout
GET /v1/auth/me
GET /v1/users
GET /v1/users/{user_id}
PATCH /v1/users/{user_id}
```

## Roles

```text
client
admin
```

Solo un `admin` puede cambiar `role` o `scopes` de otro usuario.

## Login

```http
POST /v1/auth/login
Content-Type: application/json
```

```json
{
  "email": "ops@comercio.com",
  "password": "una-clave-segura"
}
```

Respuesta `201`:

```json
{
  "data": {
"access_token": "eyJ...",
"refresh_token": "rt_019f704f89d77e83b3e1f07c33801024",
"token_type": "Bearer",
"expires_in": 900,
"user": {
  "id": "019f704f-89d7-7e83-b3e1-f07c33801024",
  "email": "ops@comercio.com",
  "name": "Operaciones",
  "role": "client",
  "scopes": [
    "payment_methods:read",
    "payments:create",
    "payments:read"
  ],
  "created_at": "2026-07-17T13:00:00.000Z",
  "updated_at": "2026-07-17T13:00:00.000Z"
}
  }
}
```

Usar el access token:

```http
Authorization: Bearer eyJ...
```

## Refresh

```http
POST /v1/auth/refresh
Content-Type: application/json
```

```json
{
  "refresh_token": "rt_019f704f89d77e83b3e1f07c33801024"
}
```

El refresh es opaco, se almacena hasheado y se **rota** en cada uso. Reutilizar un refresh ya rotado revoca la cadena de sesiones del usuario. La respuesta `201` entrega access y refresh nuevos; reemplazá ambos de forma atómica.

## Logout

```http
POST /v1/auth/logout
Content-Type: application/json
```

```json
{
  "refresh_token": "rt_019f704f89d77e83b3e1f07c33801024"
}
```

`refresh_token` es opcional en el schema. Al recibir éxito, eliminá localmente access y refresh tokens.

## Usuario actual

```http
GET /v1/auth/me
Authorization: Bearer <jwt>
```

```json
{
  "data": {
"id": "019f704f-89d7-7e83-b3e1-f07c33801024",
"email": "ops@comercio.com",
"name": "Operaciones",
"role": "client",
"scopes": [
  "payment_methods:read",
  "payments:create",
  "payments:read"
],
"created_at": "2026-07-17T13:00:00.000Z",
"updated_at": "2026-07-17T13:00:00.000Z"
  }
}
```

## Listar usuarios

Solo `admin`.

```http
GET /v1/users?limit=50&offset=0
Authorization: Bearer <jwt>
```

El listado usa `data` y `pagination` con `limit`, `offset` y `total`.

## Obtener y actualizar un usuario

```http
GET /v1/users/{user_id}
PATCH /v1/users/{user_id}
Authorization: Bearer <jwt>
Content-Type: application/json
```

Campos opcionales en `PATCH`: `email`, `name`, `role`, `scopes`. Solo un administrador puede cambiar `role` o `scopes`.

```json
{
  "name": "Operaciones de pagos",
  "scopes": [
"payment_methods:read",
"payments:create",
"payments:read",
"payments:cancel"
  ]
}
```

Scopes de negocio admitidos: `payment_methods:read`, `payments:create`, `payments:read`, `payments:cancel`, `refunds:create`.

## Errores

| Código                  | HTTP |
| ----------------------- | ---: |
| `invalid_credentials`   |  401 |
| `invalid_refresh_token` |  401 |
| `unauthorized`          |  401 |
| `insufficient_role`     |  403 |
| `user_not_found`        |  404 |
| `invalid_request`       |  400 |

Los endpoints de sesión tienen rate limiting. Ante `429`, respetá el tiempo indicado y evitá loops de login o refresh. Un `invalid_refresh_token` no es reintentable: borrá la sesión local y solicitá un login nuevo.

Source: https://docs.pagofast.com/resources/users/index.mdx