Sign in
.md

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 endpoint:

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:

{
  "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 instead. The response carries the matching personId and type, which you can pair with Get 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:

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.

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).

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 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 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)

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 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 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 — sends a numeric PIN to the customer (SMS / email).
  • Validate PIN — 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 guide.

See also