POSTLink de login

O recurso Auth dá acesso autenticado a áreas da loja sem que o usuário digite as credenciais em um formulário de login. É útil para criar links autenticados e enviá-los por e-mail ou por outros canais. Você envia o e-mail do usuário (e, se quiser, uma URL de destino) e recebe de volta uma chave de sessão e o link pronto para uso.

O recurso aceita apenas o método POST.

Gerar o link de login

Exemplo de requisição

curl -u "$EMAIL:$API_KEY" \
  -X POST "$BASE_URL/api/auth" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "admin@example.com",
  "redirect_url": "https://www.example.com/dashboard"
}'

Resposta

{
  "key": "a49a3069b7f1641e4a27feb3b1c00f95",
  "link": "https://www.venddor.com.br/auth/?ekey=a49a3069b7f1641e4a27feb3b1c00f95"
}

Quando a requisição inclui redirect_url, o link leva essa URL como parâmetro e, ao seguir o link, o usuário é redirecionado de imediato para o endereço informado:

{
  "key": "a49a3069b7f1641e4a27feb3b1c00f95",
  "link": "https://www.venddor.com.br/auth/?ekey=a49a3069b7f1641e4a27feb3b1c00f95&redirect_url=https://example.com/callback"
}

Fluxo de autenticação

1. Envie a requisição

   Faça um POST em /api/auth com os parâmetros necessários.

2. Receba o link de login

   A API gera um link seguro, com validade limitada, e o devolve na resposta.

3. O usuário segue o link

   Ao abrir o link, o usuário é autenticado sem precisar digitar a senha.

4. Redirecionamento

   Se você informou redirect_url, o usuário é levado a esse endereço depois do login.

Erros

Os códigos 400, 401 e 429 vêm da descrição do endpoint de autenticação mostrada mais abaixo nesta página; o 404 vem da descrição dos parâmetros. Os demais códigos estão em Erros.

Boas práticas

• Confirme que o e-mail existe no seu sistema antes de enviar a requisição de autenticação.
• Use HTTPS em toda a comunicação com a API.
• Defina URLs de redirecionamento que levem o usuário a destinos seguros e esperados.
• Considere implementar um limite de requisições do seu lado para evitar abuso da autenticação.
• Para testes, crie um usuário de teste dedicado em vez de usar as credenciais de administrador de produção.

Outras descrições do mesmo endpoint

A documentação de referência descreve POST /api/auth de três formas. A primeira é a que está acima. As outras duas aparecem em páginas próprias, com parâmetros e respostas diferentes, e são reproduzidas aqui como a documentação as apresenta.

Autenticação por e-mail e senha

Nesta descrição, o endpoint solicita uma chave e um link de acesso à API da Venddor, e apenas POST é aceito. Os parâmetros são:

{
  "email": "user@example.com",
  "password": "your_secure_password"
}

Resposta de exemplo:

{
  "status": "success",
  "data": {
    "api_key": "abcdef123456789abcdef123456789",
    "expires_at": "2025-05-16T12:00:00Z",
    "user_id": 12345
  }
}

Guarde a chave de API em local seguro e envie-a no cabeçalho Authorization em todas as requisições seguintes.

Autenticação por id do usuário

A descrição da entidade Auth mostra ainda um formato em que o usuário é indicado pelo id e o link pode ter validade configurada:

curl -X POST \
  https://www.venddor.com.br/api/auth \
  --user admin@example.com:APIkey \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": 42,
    "redirect_url": "https://www.venddor.com.br/admin/dashboard",
    "expiry_time": 7200
  }'

Resposta de exemplo:

{
  "session_key": "AbCdEf123456",
  "auth_url": "https://www.venddor.com.br/auth/login?key=AbCdEf123456&redirect_url=https%3A%2F%2Fwww.venddor.com.br%2Fadmin%2Fdashboard",
  "expiry": "2025-04-15T14:34:56Z"
}

Para gerar um link de login direto para um usuário, basta enviar o user_id:

curl -X POST \
  https://www.venddor.com.br/api/auth \
  --user admin@example.com:APIkey \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": 42
  }'

Para um link de redefinição de senha com validade mais curta, envie o redirect_url da página de redefinição e um expiry_time menor:

curl -X POST \
  https://www.venddor.com.br/api/auth \
  --user admin@example.com:APIkey \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": 42,
    "redirect_url": "https://www.venddor.com.br/account/reset_password",
    "expiry_time": 1800
  }'

Veja também

• Autenticação
• Erros
• Convenções