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

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

client
admin

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

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

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

Respuesta 201:

{
  "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:

Authorization: Bearer eyJ...

Refresh

POST /v1/auth/refresh
Content-Type: application/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

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

{
  "refresh_token": "rt_019f704f89d77e83b3e1f07c33801024"
}

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

Usuario actual

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

{
  "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.

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

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.

{
  "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.