Skip to main content
A AWSales usa JWT (JSON Web Tokens) para autenticação. Toda request autenticada deve incluir um access token válido no header Authorization. Existem três formas de obter tokens: email/senha, OAuth (Google ou Microsoft) e magic link (sem senha).

​
Métodos de autenticação em resumo

MétodoIdeal paraRequer senha?
Email e senhaCadastro e login padrãoSim
OAuth (Google / Microsoft)SSO e contas corporativasNão
Magic linkAcesso rápido sem senhaNão
Todos os três métodos retornam o mesmo par de tokens (accessToken + refreshToken) em caso de sucesso.

​
Fluxo de email e senha

O ciclo de vida completo, desde a criação da conta até chamadas autenticadas à API.
1

Cadastro

Registre uma nova conta com um token de convite. O usuário é automaticamente adicionado à organização que o convidou.
curl -X POST https://api.awsales.io/studio/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "password": "S3cur3P@ssw0rd!",
    "invitationToken": "inv_tok_abc123def456"
  }'
2

Verificar email

Após o cadastro, um OTP é enviado para o email do usuário. Envie o OTP para solicitar um código de verificação e depois verifique-o.
# 1. Request the OTP
curl -X POST https://api.awsales.io/studio/otps \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "user@example.com",
    "context": "EMAIL_VERIFICATION"
  }'
# Returns: { "otpId": "019525fe-8f80-7afa-f2be-0c2d4e6a8b0e" }

# 2. Verify the code
curl -X POST https://api.awsales.io/studio/auth/email-verification \
  -H "Content-Type: application/json" \
  -d '{
    "otpId": "019525fe-8f80-7afa-f2be-0c2d4e6a8b0e",
    "code": "482916"
  }'
# 204 No Content on success
3

Login

Troque as credenciais por um access token e um refresh token.
curl -X POST https://api.awsales.io/studio/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "S3cur3P@ssw0rd!"
  }'
Response de sucesso:
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "expiresIn": 3600
}
4

Usar o token

Inclua o access token no header Authorization em todas as requests autenticadas.
curl https://api.awsales.io/studio/profile \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Fluxo OAuth

Autentique via Google ou Microsoft sem senha.
1

Obter a URL de autorização

Solicite uma URL de autorização OAuth à API. Provedores suportados: GoogleOAuth, MicrosoftOAuth.
curl -X POST https://api.awsales.io/studio/auth/oauth/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "GoogleOAuth",
    "redirectUri": "https://studio.awsales.io/auth/callback",
    "state": "random_csrf_token_xyz"
  }'
2

Usuário autoriza no provedor

O usuário é redirecionado para o Google ou Microsoft, faz login e concede acesso. O provedor redireciona de volta para a sua redirectUri com os parâmetros code e state.
3

Trocar o código por tokens

Envie o código de autorização de volta para completar o fluxo.
curl -X POST https://api.awsales.io/studio/auth/oauth/callback \
  -H "Content-Type: application/json" \
  -d '{
    "code": "4/0AX4XfWh...",
    "provider": "GoogleOAuth",
    "state": "random_csrf_token_xyz"
  }'
Login sem senha via código único enviado por email.
1

Enviar o OTP

Solicite um OTP de magic auth para o email do usuário.
curl -X POST https://api.awsales.io/studio/otps \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "user@example.com",
    "context": "MAGIC_AUTH"
  }'
2

Fazer login com o código

O usuário recebe um código por email. Troque-o por tokens.
curl -X POST https://api.awsales.io/studio/auth/sign-in/magic-auth \
  -H "Content-Type: application/json" \
  -d '{
    "otpId": "019525fe-8f80-7afa-f2be-0c2d4e6a8b0e",
    "code": "739201"
  }'

​
Gerenciamento de tokens

​
Tipos de token

TokenFinalidadeValidade
accessTokenAutentica toda request à API via header Authorization: BearerCurta duração (veja expiresIn em segundos)
refreshTokenObtém um novo access token sem precisar reautenticarLonga duração

​
Renovação de tokens

Quando o access token expira, use o refresh token para obter um novo par sem exigir que o usuário faça login novamente.
Monitore o valor de expiresIn e renove proativamente antes do token expirar. Isso evita requests falhas por tokens expirados.
Boas práticas de armazenamento de tokens:
  • Armazene tokens em cookies seguros (HTTP-only) ou sessões server-side.
  • Nunca armazene tokens em localStorage ou sessionStorage em produção — eles são acessíveis a ataques XSS.
  • Em mobile, use o armazenamento seguro da plataforma (Keychain no iOS, EncryptedSharedPreferences no Android).
Nunca exponha access tokens ou refresh tokens em bundles JavaScript client-side, parâmetros de URL ou logs do navegador. Trate tokens como senhas.

​
Acesso multi-organização

Um usuário pode pertencer a múltiplas organizações. Quando o login retorna 403 com o código auth.organization_selection_required, o usuário precisa selecionar uma organização antes de prosseguir.
1

Login retorna 403

{
  "statusCode": 403,
  "message": "auth.organization_selection_required"
}
A response inclui um token temporário que permite chamar o endpoint de troca.
2

Trocar de organização

Chame o endpoint de troca de organização com o organizationId desejado.
curl -X POST https://api.awsales.io/studio/profile/switch-organization \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <temporary-token>" \
  -d '{
    "organizationId": "019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2"
  }'
Os novos tokens são vinculados à organização selecionada. Todas as requests subsequentes operam dentro do contexto dessa organização.

​
Responses 403 especiais durante o login

O login pode retornar 403 com sub-códigos que exigem ações específicas:
CódigoSignificadoO que fazer
auth.organization_selection_requiredUsuário pertence a múltiplas organizaçõesChame Trocar Organização
auth.otp_verification_requiredEmail ainda não verificadoComplete a verificação de OTP
auth.method_not_allowedConta usa um método de autenticação diferenteUse o fluxo correto (ex: OAuth em vez de senha)

​
Próximos passos

Tratamento de Erros

Entenda os formatos de response de erro e implemente recuperação robusta de erros.

Referência da API: Auth

Referência completa dos endpoints para todas as rotas de autenticação.