Como funciona a autenticação da Storefront API.
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.
Os cookies são definidos pelo servidor com as flags httpOnly, Secure e SameSite=Lax. Isso garante que:
Os cookies de sessão são isolados por tipo de usuário:
| Cookie | httpOnly | Descrição |
|---|---|---|
| authJwtClient | Sim | Token JWT do cliente (storefront). Não acessível por JavaScript. |
| sessionClient | Não | Indicador 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. |
| refreshToken | Sim | Token de refresh para renovação automática. SameSite=Strict. |
document.cookie para verificar sua presença.
Para que os cookies sejam enviados automaticamente, inclua credentials: 'include' em toda chamada fetch():
Os cookies httpOnly funcionam corretamente com domínios customizados. O comportamento depende do domínio de origem:
| Origem | Cookie Domain | Comportamento |
|---|---|---|
*.acessocomercial.com | .acessocomercial.com | Compartilhado 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. |
domain são automaticamente limitados ao domínio exato que os definiu.
Use a mutation clientLogin com email e senha. O servidor retorna os dados do usuário e define o cookie de sessão.
Use a mutation clientGoogleLogin com o token OAuth do Google.
Use a mutation clientSignup para criar uma conta. O usuário é autenticado automaticamente após o cadastro.
Use a query auth para verificar se o usuário está autenticado e obter os dados da 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.
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.
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 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
}query CheckAuth {
auth {
isAuthenticated
user {
name
email
}
}
}{
"data": null,
"errors": [{
"message": "Not authenticated",
"extensions": {
"code": "UNAUTHENTICATED"
}
}]
}