> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar com a API do Alana Shopping B2B usando chaves de API ou tokens de sessão.

## Métodos de autenticação

A API do Alana Shopping B2B suporta dois métodos de autenticação dependendo do seu caso de uso.

### Chaves de API (recomendado para integrações)

Chaves de API são a forma recomendada de autenticar acesso programático. Cada chave tem escopo para um workspace e pode ter permissões granulares.

```bash theme={null}
curl -H "Authorization: Bearer sk_live_abc123..." \
  https://app.alana.shopping/api/workspace/{workspaceId}/brands
```

Características da chave:

* Prefixadas com `sk_live_` para chaves de produção
* Mostradas apenas uma vez na criação — armazene com segurança
* Podem ser revogadas instantaneamente sem afetar outras chaves
* Rastreiam `last_used_at` para fins de auditoria
* Expiram com base na política de segurança do seu workspace

### Autenticação de sessão (navegador/dashboard)

Ao usar o dashboard, a autenticação é gerenciada via sessões do Supabase Auth. Este método suporta email/senha, magic links e provedores OAuth (Google, GitHub).

Tokens de sessão são gerenciados automaticamente pelo cliente do navegador e não são destinados a integrações de API.

## Contexto de workspace

Toda requisição de API opera dentro de um contexto de workspace. O ID do workspace faz parte do caminho da URL:

```
/api/workspace/{workspaceId}/...
```

Sua chave de API deve pertencer ao workspace especificado. Requisições para um workspace onde a chave não tem associação retornarão `403 Forbidden`.

## Acesso baseado em funções

Chaves de API herdam as permissões do usuário que as criou. A hierarquia de funções controla quais operações são permitidas:

| Função     | Nível | Capacidades                                                          |
| ---------- | ----- | -------------------------------------------------------------------- |
| **Owner**  | 4     | Controle total — cobrança, deletar workspace, transferir propriedade |
| **Admin**  | 3     | Gerenciar membros, marcas, catálogos, chaves de API                  |
| **Editor** | 2     | Criar e modificar produtos, catálogos                                |
| **Viewer** | 1     | Acesso somente leitura a todos os recursos                           |

<Info>
  Chaves de API criadas por um admin não podem realizar operações de nível owner como deletar o workspace ou transferir propriedade.
</Info>

## Melhores práticas de segurança

<AccordionGroup>
  <Accordion title="Rotacione chaves regularmente">
    Crie novas chaves e revogue as antigas em um cronograma regular. Use o campo `expiresAt` ao criar chaves para forçar expiração automática.
  </Accordion>

  <Accordion title="Use permissões mínimas">
    Crie chaves separadas para diferentes integrações com apenas as permissões que cada uma precisa.
  </Accordion>

  <Accordion title="Nunca exponha chaves em código client-side">
    Chaves de API devem ser usadas apenas server-side. Nunca as inclua em JavaScript de navegador, apps móveis ou repositórios públicos.
  </Accordion>

  <Accordion title="Monitore uso">
    Verifique timestamps `last_used_at` e logs de auditoria regularmente. Revogue qualquer chave que mostre atividade inesperada.
  </Accordion>
</AccordionGroup>