Autenticação via Personal Access Tokens (PAT)

1. Visão Geral

O Adventure Keeper permite que clientes externos (como o Foundry VTT, Roll20, bots de automação e scripts) consumam e alimentem dados na plataforma sem expor credenciais interativas de sessão ou passkeys WebAuthn.

A autenticação é realizada através de Personal Access Tokens (PAT) com o prefixo visível ak_pat_.

2. Gerando um Token de Acesso

Na aplicação web (app.adventurekeeper.com.br), navegue até Configurações > Segurança.
No card Tokens de Acesso Pessoal (PAT), clique em Novo Token de API.
Defina um nome identificador (ex: “Foundry VTT — Campanha Strahd”).
Selecione os escopos necessários e se o token deve ser restrito a uma única campanha ou ter acesso a todas as suas campanhas.
Copie o token gerado imediatamente. Por segurança, o token completo é exibido apenas uma vez.

3. Formato do Token & Armazenamento

Formato exibido: ak_pat_ seguido de caracteres criptograficamente seguros (ex: ak_pat_a1b2c3d4e5f6...).
Segurança no banco: O banco de dados do Adventure Keeper armazena exclusivamente o hash SHA-256 do token. O valor em texto claro nunca é registrado.

4. Cabeçalho de Autorização HTTP

Em todas as requisições autenticadas para a API, envie o token no header Authorization:

Authorization: Bearer ak_pat_seu_token_aqui

5. Escopos Disponíveis

Escopo	Descrição
`sessions:read`	Leitura de sessões e diários de bordo.
`sessions:write`	Criação e ingestão de novas sessões e notas.
`campaigns:read`	Leitura de metadados das campanhas do titular.
`campaigns:write`	Atualização de configurações das campanhas.

Atenção: Para o endpoint de ingestão VTT (/api/v1/integrations/sessions), o token deve possuir obrigatoriamente o escopo sessions:write.

6. Verificando o Token (`GET /verify`)

Você pode testar se o seu token é válido e inspecionar seus escopos antes de realizar envios:

curl -X GET "https://app.adventurekeeper.com.br/api/v1/integrations/sessions/verify" \
  -H "Authorization: Bearer ak_pat_seu_token_aqui"

Resposta de Sucesso (200 OK):

{
  "data": {
    "valid": true,
    "user": {
      "id": 1,
      "fullName": "Mestre Bruno",
      "email": "gm@adventurekeeper.com.br"
    },
    "token": {
      "id": "c7a8b9d0-1234-5678-90ab-cdef12345678",
      "name": "Foundry Integration",
      "scopes": ["sessions:write"],
      "campaignId": null
    }
  }
}