---
title: 'Autenticación'
description: 'Cómo obtener y usar el token x-guper-authorization.'
---

# Autenticación

La mayoría de las APIs de Guper requieren un **token de autorización** enviado en cada solicitud mediante el header `x-guper-authorization`. Esta página cubre cómo obtener ese token y cómo usarlo.

## Credenciales

Cada cuenta de acceso a la API recibe dos credenciales:

- **API Key** (`x-guper-apikey`) — identificador público de tu cuenta.
- **API Secret** (`x-guper-apisecret`) — valor secreto, trátalo como una contraseña.

El par inicial lo genera el equipo de integración de Guper. Mantén el secret seguro — nunca debe exponerse en el navegador ni subirse a un repositorio.

## Generando un token

Intercambia las credenciales por un token de corta duración en el endpoint [Get token](/docs/{lang}/api-reference/connect/api/get-token):

```bash
curl -X GET "https://{organization}.myguper.com/api/connect/token" \
  -H "x-guper-apikey: <tu apikey>" \
  -H "x-guper-apisecret: <tu apisecret>"
```

La respuesta contiene el token y su vencimiento:

```json
{
  "accessToken": "c074cb9bd30d7b431230877facb45e0a06790e93dea6a728cef9fdaf656bf349",
  "expiresIn":   "2023-08-11T15:13:00-03:00",
  "dateTime":    "2023-08-11T09:13:00-03:00"
}
```

Los tokens son de corta duración. Guárdalos en caché en tu backend hasta que venzan y renuévalos con anticipación — nunca llames al endpoint de auth en cada solicitud.

### Autenticando a un usuario

Si tu integración necesita actuar en nombre de un usuario específico (login + contraseña), usa [Auth](/docs/{lang}/api-reference/connect/user/auth) en su lugar. La respuesta trae el `personId` y `type` correspondientes, que puedes combinar con [Get access token](/docs/{lang}/api-reference/connect/user/token/access-token) para emitir un token de sesión de 30 días para ese usuario.

## Usando el token

Envía el token en el header `x-guper-authorization` en cada solicitud protegida:

```bash
curl -X POST "https://{organization}.myguper.com/api/loyalty/rewardByOrder" \
  -H "x-guper-authorization: <tu token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

Puedes verificar a quién pertenece un token con [Get user by token](/docs/{lang}/api-reference/connect/user/token/auth).

## Inicio de sesión por persona (OAuth 2.1)

Además del camino `apiKey`/`apiSecret` de arriba — que identifica una **integración** — existe un segundo camino, que identifica a una **persona**: OAuth 2.1 con PKCE, usado por los asistentes de IA.

La diferencia que importa:

| | `apiKey` / `apiSecret` | OAuth 2.1 |
|---|---|---|
| identifica | una integración (sistema) | una persona |
| quién la registra | el equipo de integración | nadie — registro dinámico |
| permisos | de la cuenta de acceso | los del perfil de la persona en el panel |
| revocar | cambiar la credencial de todos | desactivar a ese usuario |

Ambos conviven, y **nada cambia para quien ya integra**. Usa OAuth cuando el acceso sea de una persona y deba respetar su perfil; sigue con `apiKey`/`apiSecret` para integración servidor a servidor.

El flujo completo, los endpoints y lo que tu cliente debe respetar están en [Guper por IA (MCP)](/docs/{lang}/guides/mcp).

## Proof of Work (PoW)

Los endpoints de login que aceptan `login` + `password` soportan una capa opcional de **Proof of Work** que mitiga ataques de fuerza bruta y credential stuffing.

### Como funciona

Antes de enviar las credenciales, el cliente solicita un desafio al endpoint [Generar desafio](/docs/{lang}/api-reference/connect/pow/challenge). El servidor retorna una cadena `challenge` aleatoria y un `target` — un umbral hexadecimal de 64 caracteres. El cliente debe encontrar un `nonce` tal que:

```
SHA-256(challenge + nonce) <= target
```

El `challenge` y `nonce` resueltos se incluyen entonces en la solicitud [Auth](/docs/{lang}/api-reference/connect/user/auth) junto con `login` y `password`.

### Anti-paralelismo

Cada nuevo challenge para el mismo login **invalida el anterior**. Un atacante creando miles de navegadores contra el mismo email descubre que solo el ultimo challenge es valido — los demas intentos fallan en la autenticacion.

### Escalada de dificultad

El servidor rastrea cuantos challenges fueron solicitados para un login dado dentro de una ventana deslizante de 15 minutos. Cuantas mas solicitudes, mas dificil se vuelve el desafio (escala exponencial). Despues de que la ventana pasa sin nuevas solicitudes, la dificultad vuelve al nivel base.

| Solicitudes en ventana | Tiempo aproximado de resolucion |
|---|---|
| 1 | menos de 1 segundo |
| 5 | ~4 segundos |
| 10 | ~78 segundos |
| 13+ | excede el TTL del challenge (bloqueo efectivo) |

### Expiracion del challenge

Cada challenge es valido por **5 minutos**. Si el cliente no envia la solucion dentro de esa ventana, el challenge expira y debe solicitarse uno nuevo.

### Ejemplo (JavaScript)

```javascript
async function loginWithPoW(baseUrl, login, password) {
    // 1. Solicitar un desafio
    const challengeRes = await fetch(`${baseUrl}/api/connect/pow/challenge`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ login })
    });
    const { challenge, target } = await challengeRes.json();

    // 2. Resolver: encontrar nonce donde SHA-256(challenge + nonce) <= target
    let nonce = 0;
    const encoder = new TextEncoder();
    while (true) {
        const data = encoder.encode(challenge + nonce.toString());
        const buf = await crypto.subtle.digest('SHA-256', data);
        const hex = [...new Uint8Array(buf)]
            .map(b => b.toString(16).padStart(2, '0')).join('');
        if (hex <= target) break;
        nonce++;
    }

    // 3. Autenticar con la prueba resuelta
    const authRes = await fetch(`${baseUrl}/api/connect/auth`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ login, password, challenge, nonce: nonce.toString() })
    });
    return authRes.json(); // { personId, type, dateTime }
}
```

Para aplicaciones en el navegador, ejecute el paso 2 dentro de un [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) para no bloquear el hilo principal de la interfaz.

### Integracion

Los campos de PoW (`challenge`, `nonce`) son actualmente **opcionales** en el endpoint Auth. Los clientes que no los envian omiten la verificacion PoW. El panel admin de Guper y la pagina de autorizacion OAuth ya incluyen PoW en sus flujos de inicio de sesion.

**Estos campos se volveran obligatorios en una version futura.** Todos los clientes que llaman al endpoint Auth deben integrar el flujo de Proof of Work lo antes posible.

## Modo público

Un pequeño conjunto de endpoints soporta el **Modo público** — aceptan la misma solicitud **sin** el header `x-guper-authorization`. En modo público la respuesta no incluye datos del cliente ni tokens de confirmación; solo se devuelven los valores que se aplicarían.

Por ejemplo, la variante pública de [Reward by Order](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order) te permite simular el cashback que un pedido *generaría*, sin registrar nada.

## Segundo factor por PIN

Los endpoints que involucran canjes de alto valor (como el checkout de loyalty) pueden requerir un paso adicional con PIN:

- [Generate PIN](/docs/{lang}/api-reference/register/customer/pin/generate) — envía un PIN numérico al cliente (SMS / email).
- [Validate PIN](/docs/{lang}/api-reference/register/customer/pin/validate) — confirma el código que el cliente capturó en el POS.

## Errores

| Status | Significado |
|---|---|
| `401` | Token inválido o expirado. Renuévalo y reintenta. |
| `403` | El token es válido, pero no tiene permiso para el recurso. |
| `5xx` | Problema del lado del servidor. Si persiste, contacta a soporte. |

## Sandbox

Para pruebas en un entorno fuera de producción, usa las credenciales documentadas en la guía [Sandbox](/docs/{lang}/guides/sandbox).

## Ver también

- [Get token](/docs/{lang}/api-reference/connect/api/get-token) — apikey + apisecret → access token
- [Auth](/docs/{lang}/api-reference/connect/user/auth) — login + contraseña → personId
- [Generar desafio](/docs/{lang}/api-reference/connect/pow/challenge) — desafio Proof of Work para login
- [Get access token](/docs/{lang}/api-reference/connect/user/token/access-token) — emite un token de sesión de 30 días para un usuario
- [Guper por IA (MCP)](/docs/{lang}/guides/mcp) — inicio de sesión por persona, para asistentes de IA
- [Get user by token](/docs/{lang}/api-reference/connect/user/token/auth) — resuelve un token de sesión al usuario propietario
