GUIA

Autenticação

Como funciona a autenticação da Storefront API.

Visão Geral

A Storefront API usa cookies httpOnly para autenticação. Quando o cliente faz login, o servidor define cookies de sessão automaticamente. Não é necessário gerenciar tokens manualmente.

Cookies de Sessão

Os cookies são definidos pelo servidor com as flags httpOnly, Secure e SameSite=Lax. Isso garante que:

  • JavaScript no frontend não consegue acessar o token (proteção contra XSS)
  • Cookies só são enviados em conexões HTTPS
  • Cookies são enviados em navegações top-level e requests same-origin

Os cookies de sessão são isolados por tipo de usuário:

CookiehttpOnlyDescrição
authJwtClientSimToken JWT do cliente (storefront). Não acessível por JavaScript.
sessionClientNãoIndicador de sessão. Acessível por JavaScript para que o frontend saiba se o usuário está logado sem precisar fazer uma request à API. Valor: "1" ou JSON com dados da sessão. Definido automaticamente pelo servidor junto com o authJwtClient.
refreshTokenSimToken de refresh para renovação automática. SameSite=Strict.
sessionClient no frontend: Use este cookie para verificar o estado de login no lado do cliente (ex: mostrar/esconder botão de login, exibir nome do usuário). Não é necessário armazená-lo manualmente — o navegador o gerencia automaticamente. Basta ler document.cookie para verificar sua presença.

Incluir Credenciais

Para que os cookies sejam enviados automaticamente, inclua credentials: 'include' em toda chamada fetch():

Domínios Customizados

Os cookies httpOnly funcionam corretamente com domínios customizados. O comportamento depende do domínio de origem:

OrigemCookie DomainComportamento
*.acessocomercial.com.acessocomercial.comCompartilhado entre subdomínios da plataforma.
Domínio customizado(não definido)Cookie vinculado ao domínio exato da loja. Funciona nativamente pois o storefront faz requests para seu próprio domínio.
Importante: Para domínios customizados, o storefront deve fazer requests para o API na mesma origem (via proxy reverso ou subdomínio). Cookies sem atributo domain são automaticamente limitados ao domínio exato que os definiu.
Frontend externo? Se o frontend roda em um domínio diferente do backend (ex: Lovable, Vercel preview), veja os Modos de Integração para entender as opções de autenticação (proxy reverso ou Bearer token).

Fluxos de Autenticação

Login com Email/Senha

Use a mutation clientLogin com email e senha. O servidor retorna os dados do usuário e define o cookie de sessão.

Login com Google

Use a mutation clientGoogleLogin com o token OAuth do Google.

Cadastro

Use a mutation clientSignup para criar uma conta. O usuário é autenticado automaticamente após o cadastro.

Verificar Estado da Sessão

Use a query auth para verificar se o usuário está autenticado e obter os dados da sessão.

Renovação Automática de Sessão

Quando o token JWT expira, o servidor tenta renovar automaticamente usando o refreshToken. Se a renovação for bem-sucedida, novos cookies são definidos transparentemente. Se falhar, o usuário precisa fazer login novamente.

Erros de Autenticação

Quando uma operação requer autenticação e o usuário não está logado, a API retorna um erro com código UNAUTHENTICATED. Veja o Guia de Erros para todos os códigos.

Request com Credenciais

JavaScript
const response = await fetch(
  '/graphql',
  {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: `mutation {
        clientLogin(input: {
          email: "user@example.com"
          password: "secret"
          hostname: "minha-loja"
        }) {
          user { name email }
        }
      }`
    })
  }
);

Verificar Sessão (via cookie)

JavaScript
// Verificar se o usuário está logado (sem request à API)
function hasClientSession() {
  return document.cookie
    .split(';')
    .some((c) => c.trim().startsWith('sessionClient='));
}

if (hasClientSession()) {
  // Usuário logado — exibir área logada
} else {
  // Usuário não logado — exibir botão de login
}

Verificar Sessão (via API)

GraphQL
query CheckAuth {
  auth {
    isAuthenticated
    user {
      name
      email
    }
  }
}

Erro de Autenticação

JSON
{
  "data": null,
  "errors": [{
    "message": "Not authenticated",
    "extensions": {
      "code": "UNAUTHENTICATED"
    }
  }]
}