> ## Documentation Index
> Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Autenticação
> Implemente o OAuth 2.1 para autorizar usuários da Vendaze no seu aplicativo.
A Vendaze API usa **OAuth 2.1 Authorization Code flow** com `client_secret`. Esta é uma integração server-side: todas as trocas de token precisam acontecer no seu back-end. O `client_secret` nunca pode ser exposto em código no browser, binários de app mobile ou qualquer ambiente que o usuário final possa inspecionar.
Antes de continuar, você precisa de um `client_id` e `client_secret`. Veja [Registre seu aplicativo](/pt/guides/register-app).
## Como funciona
Seu servidor constrói a URL de autorização e redireciona o browser do usuário para ela.
O usuário seleciona um workspace e visualiza os escopos solicitados na tela de consentimento da
Vendaze. Ele pode apenas aprovar ou negar o acesso completo, sem opção de selecionar escopos
individualmente.
A Vendaze redireciona o browser de volta para sua `redirect_uri` com um `code` de curta duração.
Seu servidor troca o code por um `access_token` e `refresh_token` via requisição back-end.
Inclua o `access_token` como Bearer token em toda requisição.
Access tokens expiram em 1 hora. Use o `refresh_token` para obter um novo sem interação do
usuário.
## Passo 1 - Redirecionar o usuário
Construa a URL de autorização e redirecione o **browser** do usuário para ela. Isso deve ser uma navegação de browser, não uma requisição HTTP server-side. Não use `fetch`, `axios`, `curl` ou qualquer cliente HTTP para chamar este endpoint. O usuário precisa ser redirecionado para que possa fazer login e aprovar o acesso na tela de consentimento da Vendaze.
```
GET https://api.vendaze.com/oauth/authorize
?client_id=SEU_CLIENT_ID
&redirect_uri=https://meuapp.com/oauth/callback
&response_type=code
&state=TOKEN_CSRF_ALEATORIO
```
Exemplo de redirecionamento em uma aplicação web:
```js theme={null}
const params = new URLSearchParams({
client_id: 'SEU_CLIENT_ID',
redirect_uri: 'https://meuapp.com/oauth/callback',
response_type: 'code',
state: crypto.randomUUID(),
});
// Armazene o state para verificação CSRF no callback
sessionStorage.setItem('oauth_state', params.get('state'));
// Navegue o browser. Nunca use fetch/axios aqui.
window.location.href = `https://api.vendaze.com/oauth/authorize?${params}`;
```
| Parâmetro | Obrigatório | Descrição |
| --------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `client_id` | Sim | O client ID do seu aplicativo. |
| `redirect_uri` | Sim | Deve corresponder exatamente a uma URI registrada. |
| `response_type` | Sim | Deve ser `code`. |
| `state` | Não | String aleatória que você gera. Retornada sem alteração. Fortemente recomendada para proteção contra CSRF. |
Sempre inclua o `state` e verifique-o no callback. Rejeite qualquer callback onde o `state`
recebido não bate com o que você enviou. Isso protege contra ataques de CSRF.
## Passo 2 - Usuário autoriza
O usuário seleciona o workspace e visualiza os escopos solicitados na tela de consentimento da Vendaze. Ele pode apenas aprovar ou negar o acesso completo, sem opção de selecionar escopos individualmente. Nenhuma ação necessária do seu lado durante este passo.
## Passo 3 - Receber o callback
Após aprovar, o usuário é redirecionado para sua `redirect_uri`:
```
https://meuapp.com/oauth/callback?code=AUTH_CODE&state=SEU_STATE
```
Verifique que o `state` bate com o que você armazenou e troque o code pelos tokens. Se o usuário recusar a autorização:
```
https://meuapp.com/oauth/callback?error=access_denied&state=SEU_STATE
```
Trate o parâmetro `error` e exiba uma mensagem adequada ao usuário.
## Passo 4 - Trocar o code pelos tokens
Códigos de autorização expiram em 10 minutos e só podem ser usados uma vez. Troque imediatamente
após receber o callback.
Esta requisição deve ser feita pelo seu servidor, nunca pelo browser.
```bash theme={null}
curl -X POST https://api.vendaze.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=AUTH_CODE_DO_CALLBACK&client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET"
```
**Resposta (200):**
```json theme={null}
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"workspace_slug": "acme-corp"
}
```
| Campo | Descrição |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `access_token` | Use em toda requisição à API. Expira em 1 hora. |
| `refresh_token` | Usado para renovar o access token. Válido por 60 dias se utilizado regularmente. |
| `token_type` | Sempre `Bearer`. |
| `expires_in` | Segundos até o access token expirar. Sempre 3600. |
| `workspace_slug` | Slug do workspace autorizado pelo usuário. Use para identificar qual conta está conectada no seu app. |
## Armazenamento de tokens
Armazene os dois tokens com segurança no servidor. As seguintes práticas se aplicam:
* **`access_token`:** curta duração (1 hora). Armazene em memória ou cache rápido. Nunca em localStorage ou cookies acessíveis ao JavaScript.
* **`refresh_token`:** longa duração (60 dias). Armazene criptografado no banco de dados, associado ao usuário e workspace. É a credencial que permite manter o acesso sem interação do usuário.
* Nunca logue nenhum dos tokens. Nunca os inclua em URLs ou query strings.
* Nunca os exponha em respostas da API para o seu próprio front-end. O front-end deve chamar seu back-end, que chama a Vendaze.
## Passo 5 - Fazer requisições à API
Inclua o `access_token` em toda requisição como Bearer token:
```bash theme={null}
curl https://api.vendaze.com/v1/people \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```
O contexto do workspace é resolvido automaticamente a partir do token. Você nunca envia um identificador de workspace nas requisições.
## Passo 6 - Renovar o access token
Access tokens expiram em 1 hora. Renove usando o refresh token antes da expiração, ou reativamente quando receber o erro `token_expired`.
```bash theme={null}
curl -X POST https://api.vendaze.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=SEU_REFRESH_TOKEN&client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET"
```
A resposta é idêntica ao Passo 4. Substitua os dois tokens no seu lado. Um novo `refresh_token` é emitido a cada renovação e o anterior é imediatamente invalidado.
Refresh tokens expiram se ficarem sem uso por 60 dias. A cada renovação, a janela de 60 dias é
reiniciada. Se expirar, o usuário precisa passar pelo fluxo completo de autorização novamente.
## Revogar acesso
Para desconectar um workspace do seu aplicativo, revogue o access token:
```bash theme={null}
curl -X POST https://api.vendaze.com/oauth/revoke \
-H "Content-Type: application/json" \
-d '{
"token": "ACCESS_TOKEN",
"client_id": "SEU_CLIENT_ID",
"client_secret": "SEU_CLIENT_SECRET"
}'
```
Sempre envie o `access_token`, não o `refresh_token`. O endpoint de revogação precisa de um JWT
para identificar o usuário e remover o grant de autorização.
Após revogar, delete os dois tokens do seu armazenamento. O usuário precisará re-autorizar se quiser reconectar.
***
Próximo: [Faça sua primeira requisição](/pt/guides/first-request) para usar seu access token em uma chamada real à API.