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
- Get token — apikey + apisecret → access token
- Auth — login + password → personId
- Generate challenge — Proof of Work challenge for login
- Get access token — issues a 30-day session token for a user
- Guper through AI (MCP) — per-person sign-in, for AI assistants
- Get user by token — resolves a session token to the owning user