---
title: 'Authentication'
description: 'How to obtain and use the x-guper-authorization token.'
---

# Authentication

Most Guper APIs require an **authorization token** sent on every request via the `x-guper-authorization` header. This page covers how to obtain that token and how to use it.

## Credentials

Each API access account is provisioned with two credentials:

- **API Key** (`x-guper-apikey`) — public identifier of your account.
- **API Secret** (`x-guper-apisecret`) — secret value, treat it like a password.

The initial pair is generated by the Guper integration team. Keep the secret safe — it must never be exposed to the browser or committed to a repository.

## Generating a token

Exchange the credentials for a short-lived token at the [Get token](/docs/{lang}/api-reference/connect/api/get-token) endpoint:

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

The response contains the token and its expiration:

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

Tokens are short-lived. Cache them in your backend until they expire and refresh ahead of time — never call the auth endpoint on every request.

### Authenticating a user

If your integration needs to act on behalf of a specific user (login + password), use [Auth](/docs/{lang}/api-reference/connect/user/auth) instead. The response carries the matching `personId` and `type`, which you can pair with [Get access token](/docs/{lang}/api-reference/connect/user/token/access-token) to issue a 30-day session token for that user.

## Using the token

Send the token in the `x-guper-authorization` header on every protected request:

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

You can verify a token's owner with [Get user by token](/docs/{lang}/api-reference/connect/user/token/auth).

## Per-person sign-in (OAuth 2.1)

Besides the `apiKey`/`apiSecret` path above — which identifies an **integration** — there is a second path that identifies a **person**: OAuth 2.1 with PKCE, used by AI assistants.

The difference that matters:

| | `apiKey` / `apiSecret` | OAuth 2.1 |
|---|---|---|
| identifies | an integration (system) | a person |
| who registers it | the integration team | nobody — dynamic registration |
| permissions | of the access account | those of the person's panel profile |
| revoking | rotate everyone's credential | deactivate that one user |

Both coexist, and **nothing changes for existing integrations**. Use OAuth when the access belongs to a person and must respect their profile; stay on `apiKey`/`apiSecret` for server-to-server integration.

The full flow, the endpoints, and what your client must respect are in [Guper through AI (MCP)](/docs/{lang}/guides/mcp).

## Proof of Work (PoW)

Login endpoints that accept `login` + `password` support an optional **Proof of Work** layer that mitigates brute-force and credential-stuffing attacks.

### How it works

Before submitting credentials, the client requests a challenge from the [Generate challenge](/docs/{lang}/api-reference/connect/pow/challenge) endpoint. The server returns a random `challenge` string and a `target` — a 64-character hex threshold. The client must find a `nonce` such that:

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

The solved `challenge` and `nonce` are then included in the [Auth](/docs/{lang}/api-reference/connect/user/auth) request alongside `login` and `password`.

### Anti-parallelism

Each new challenge for the same login **invalidates the previous one**. An attacker spawning thousands of browsers against the same email finds that only the last challenge is valid — the other attempts fail at authentication time.

### Difficulty escalation

The server tracks how many challenges were requested for a given login within a sliding 15-minute window. The more requests, the harder the challenge becomes (exponential scaling). After the window passes with no new requests, difficulty returns to baseline.

| Requests in window | Approximate solve time |
|---|---|
| 1 | less than 1 second |
| 5 | ~4 seconds |
| 10 | ~78 seconds |
| 13+ | exceeds challenge TTL (effectively blocked) |

### Challenge expiration

Each challenge is valid for **5 minutes**. If the client does not submit the solution within that window, the challenge expires and a new one must be requested.

### Example (JavaScript)

```javascript
async function loginWithPoW(baseUrl, login, password) {
    // 1. Request a challenge
    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. Solve: find nonce where 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. Authenticate with the solved proof
    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 }
}
```

For browser applications, run step 2 inside a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) to avoid blocking the UI thread.

### Integration

The PoW fields (`challenge`, `nonce`) are currently **optional** on the Auth endpoint. Clients that do not send them bypass the PoW check. The Guper admin panel and OAuth authorization page already include PoW in their login flows.

**These fields will become required in a future release.** All clients that call the Auth endpoint should integrate the Proof of Work flow as soon as possible.

## Public mode

A small number of endpoints support a **Public mode** — they accept the same request **without** the `x-guper-authorization` header. In Public mode the response excludes customer data and confirmation tokens; only the values that would be applied are returned.

For example, the Public variant of [Reward by Order](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order) lets you preview the cashback that an order *would* generate, without registering anything.

## PIN second factor

Endpoints involving high-value redemptions (like loyalty checkout) can require an extra PIN step:

- [Generate PIN](/docs/{lang}/api-reference/register/customer/pin/generate) — sends a numeric PIN to the customer (SMS / email).
- [Validate PIN](/docs/{lang}/api-reference/register/customer/pin/validate) — confirms the code the customer typed at the POS.

## Errors

| Status | Meaning |
|---|---|
| `401` | Invalid or expired token. Refresh it and retry. |
| `403` | Token is valid, but lacks permission for the resource. |
| `5xx` | Server-side issue. If the outage persists, contact support. |

## Sandbox

For testing in a non-production environment use the credentials documented in the [Sandbox](/docs/{lang}/guides/sandbox) guide.

## See also

- [Get token](/docs/{lang}/api-reference/connect/api/get-token) — apikey + apisecret → access token
- [Auth](/docs/{lang}/api-reference/connect/user/auth) — login + password → personId
- [Generate challenge](/docs/{lang}/api-reference/connect/pow/challenge) — Proof of Work challenge for login
- [Get access token](/docs/{lang}/api-reference/connect/user/token/access-token) — issues a 30-day session token for a user
- [Guper through AI (MCP)](/docs/{lang}/guides/mcp) — per-person sign-in, for AI assistants
- [Get user by token](/docs/{lang}/api-reference/connect/user/token/auth) — resolves a session token to the owning user
