Autenticação e Multi-Tenancy

Todas as requisições à Perpetuus API (exceto endpoints públicos de formulários e upload) exigem dois headers obrigatórios: autenticação e identificação do tenant.

Headers Obrigatórios

Para que qualquer requisição HTTP seja aceita, configure os seguintes cabeçalhos:

Header	Descrição	Exemplo
`Authorization`	Token JWT ou Token de API de longa duração precedido por `Bearer`	`Bearer ppat_52b89...`
`x-tenant-id`	Identificador único (slug) da sua organização no Perpetuus	`acme`

Atenção: Sem o cabeçalho x-tenant-id, a API retornará erro 400 Bad Request com a mensagem Header x-tenant-id é obrigatório. Sem a autorização, retornará 401 Unauthorized.

Como Obter um Token de API

1. Pela Interface Gráfica (Recomendado)

Os tokens de longa duração (Personal Access Tokens ou PATs) são ideais para scripts permanentes, integrações via Zapier/Make e painéis de BI.

Acesse o Perpetuus CRM e vá em Configurações (ícone de engrenagem no menu lateral).
Clique na aba Organization (Organização).
Vá para a sub-aba API.
Escolha o tempo de expiração desejado (1 dia, 30 dias, 365 dias ou Sem Expiração).
Clique em Gerar Token.
Copie o token imediatamente. Por motivos de segurança, ele não será exibido novamente.

2. Gerar Programaticamente (JWT de Sessão)

Se você estiver desenvolvendo uma aplicação que interage com a conta de um usuário final em tempo real, pode gerar um JWT temporário enviando as credenciais de login:

curl -X POST "https://api.perpetuus.com.br/api/auth/local" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "desenvolvedor@empresa.com",
    "password": "SenhaSegura123!"
  }'

A resposta conterá o campo jwt, que expira em poucas horas:

{
  "jwt": "eyJhbGciOi...",
  "user": {
    "id": 12,
    "username": "desenvolvedor",
    "email": "desenvolvedor@empresa.com"
  }
}

3. Criar Token de Longa Duração via API

Com o JWT temporário gerado no passo anterior, você pode chamar o endpoint POST /users/generate-token para obter um PAT de longa duração programaticamente:

curl -X POST "https://api.perpetuus.com.br/api/users/generate-token" \
  -H "Authorization: Bearer JWT_TEMPORARIO" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration": "365d"
  }'

Os valores de expiração suportados no campo expiration são:

1d (1 dia)
30d (30 dias)
365d (365 dias)
36500d (Aproximadamente 100 anos / Sem Expiração)

Exemplo Completo de Requisição

Abaixo, veja um exemplo completo em cURL que lista os Boards da sua organização acme:

curl -X GET "https://api.perpetuus.com.br/api/boards" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API" \
  -H "x-tenant-id: acme"