---
title: 'Autenticação'
description: 'Como obter e usar o token x-guper-authorization.'
---

# Autenticação

A maioria das APIs Guper exige um **token de autorização** enviado em cada requisição através do header `x-guper-authorization`. Esta página cobre como obter esse token e como usá-lo.

## Credenciais

Cada conta de acesso à API recebe duas credenciais:

- **API Key** (`x-guper-apikey`) — identificador público da sua conta.
- **API Secret** (`x-guper-apisecret`) — valor secreto, trate como uma senha.

O par inicial é gerado pela equipe de integração da Guper. Mantenha o secret seguro — ele nunca deve ser exposto no browser ou commitado num repositório.

## Gerando um token

Troque as credenciais por um token de curta duração no 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: <sua apikey>" \
  -H "x-guper-apisecret: <seu apisecret>"
```

A resposta contém o token e seu vencimento:

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

Os tokens têm vida curta. Faça cache no seu backend até o vencimento e renove com antecedência — não chame o endpoint de auth a cada requisição.

### Autenticando um usuário

Se sua integração precisa agir em nome de um usuário específico (login + senha), use o [Auth](/docs/{lang}/api-reference/connect/user/auth). A resposta traz o `personId` e `type` correspondentes, que podem ser combinados com [Gerar token de acesso](/docs/{lang}/api-reference/connect/user/token/access-token) para emitir um token de sessão de 30 dias para esse usuário.

## Usando o token

Envie o token no header `x-guper-authorization` em cada requisição protegida:

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

Você pode verificar a quem um token pertence em [Buscar usuário pelo token](/docs/{lang}/api-reference/connect/user/token/auth).

## Login por pessoa (OAuth 2.1)

Além do caminho `apiKey`/`apiSecret` acima — que identifica uma **integração** — existe um segundo caminho, que identifica uma **pessoa**: OAuth 2.1 com PKCE, usado pelos assistentes de IA.

A diferença que importa:

| | `apiKey` / `apiSecret` | OAuth 2.1 |
|---|---|---|
| identifica | uma integração (sistema) | uma pessoa |
| quem cadastra | a equipe de integração | ninguém — registro dinâmico |
| permissões | da conta de acesso | as do perfil da pessoa no painel |
| revogar | trocar a credencial de todos | inativar aquele usuário |

Os dois convivem, e **nada muda para quem já integra**. Use OAuth quando o acesso for de uma pessoa e precisar respeitar o perfil dela; continue com `apiKey`/`apiSecret` para integração servidor-a-servidor.

O fluxo completo, os endpoints e o que o seu cliente precisa respeitar estão em [Guper por IA (MCP)](/docs/{lang}/guides/mcp).

## Proof of Work (PoW)

Os endpoints de login que aceitam `login` + `password` suportam uma camada opcional de **Proof of Work** que mitiga ataques de forca bruta e credential stuffing.

### Como funciona

Antes de enviar as credenciais, o cliente solicita um desafio ao endpoint [Gerar desafio](/docs/{lang}/api-reference/connect/pow/challenge). O servidor retorna uma string `challenge` aleatoria e um `target` — um limiar hexadecimal de 64 caracteres. O cliente deve encontrar um `nonce` tal que:

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

O `challenge` e `nonce` resolvidos sao entao incluidos na requisicao [Auth](/docs/{lang}/api-reference/connect/user/auth) junto com `login` e `password`.

### Anti-paralelismo

Cada novo challenge para o mesmo login **invalida o anterior**. Um atacante criando milhares de browsers contra o mesmo email descobre que apenas o ultimo challenge e valido — as outras tentativas falham na autenticacao.

### Escalada de dificuldade

O servidor rastreia quantos challenges foram solicitados para um dado login dentro de uma janela deslizante de 15 minutos. Quanto mais pedidos, mais dificil o desafio se torna (escala exponencial). Apos a janela passar sem novos pedidos, a dificuldade retorna ao nivel base.

| Pedidos na janela | Tempo aproximado de resolucao |
|---|---|
| 1 | menos de 1 segundo |
| 5 | ~4 segundos |
| 10 | ~78 segundos |
| 13+ | excede o TTL do challenge (bloqueio efetivo) |

### Expiracao do challenge

Cada challenge e valido por **5 minutos**. Se o cliente nao enviar a solucao dentro dessa janela, o challenge expira e um novo deve ser solicitado.

### Exemplo (JavaScript)

```javascript
async function loginWithPoW(baseUrl, login, password) {
    // 1. Solicitar um 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 onde 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 com a prova resolvida
    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 aplicacoes no browser, execute o passo 2 dentro de um [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) para nao bloquear a thread principal da interface.

### Integracao

Os campos de PoW (`challenge`, `nonce`) sao atualmente **opcionais** no endpoint Auth. Clientes que nao os enviam ignoram a verificacao PoW. O painel admin Guper e a pagina de autorizacao OAuth ja incluem PoW em seus fluxos de login.

**Esses campos se tornarao obrigatorios em uma versao futura.** Todos os clientes que chamam o endpoint Auth devem integrar o fluxo de Proof of Work o mais breve possivel.

## Modo Público

Um pequeno conjunto de endpoints suporta o **Modo Público** — eles aceitam a mesma requisição **sem** o header `x-guper-authorization`. No modo Público a resposta não inclui dados do cliente nem token de confirmação; apenas os valores que seriam aplicados são retornados.

Por exemplo, a variante Pública de [Acúmulo por pedido](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order) permite simular o cashback que um pedido *geraria*, sem registrar nada.

## Segundo fator por PIN

Endpoints envolvendo resgates de alto valor (como o checkout do loyalty) podem exigir uma etapa extra de PIN:

- [Gerar PIN](/docs/{lang}/api-reference/register/customer/pin/generate) — envia um PIN numérico ao cliente (SMS / email).
- [Validar PIN](/docs/{lang}/api-reference/register/customer/pin/validate) — confirma o código que o cliente digitou no POS.

## Erros

| Status | Significado |
|---|---|
| `401` | Token inválido ou expirado. Renove e tente de novo. |
| `403` | Token é válido, mas não tem permissão para o recurso. |
| `5xx` | Erro no servidor. Se persistir, contate o suporte. |

## Sandbox

Para testes em ambiente não-produção, use as credenciais documentadas no guia [Sandbox](/docs/{lang}/guides/sandbox).

## Veja também

- [Get token](/docs/{lang}/api-reference/connect/api/get-token) — apikey + apisecret → access token
- [Auth](/docs/{lang}/api-reference/connect/user/auth) — login + senha → personId
- [Gerar desafio](/docs/{lang}/api-reference/connect/pow/challenge) — desafio Proof of Work para login
- [Gerar token de acesso](/docs/{lang}/api-reference/connect/user/token/access-token) — emite um token de sessão de 30 dias para um usuário
- [Guper por IA (MCP)](/docs/{lang}/guides/mcp) — login por pessoa, para assistentes de IA
- [Buscar usuário pelo token](/docs/{lang}/api-reference/connect/user/token/auth) — resolve um token de sessão para o usuário dono
