Autenticação

OAuth do Notion (JWT)

O IVGraph autentica usuários pelo fluxo OAuth2 do Notion. Não há cadastro com nome de usuário e senha.

Fluxo

User clicks "Sign in with Notion"
        |
        v
GET /api/integrations/auth/notion/
        |  -> Redirects to Notion consent screen
        v
User authorizes IVGraph in Notion
        |
        v
Notion redirects to /api/integrations/auth/notion/callback?code=...
        |  -> Backend exchanges code for Notion token
        |  -> Creates/updates Django user
        |  -> Issues JWT tokens
        v
Redirect to dashboard with tokens in URL fragment

Tokens JWT

Token	Validade	Finalidade
Token de acesso	4 horas	Autenticação na API
Token de renovação	7 dias	Obter um novo token de acesso

Como usar o token de acesso:

curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  "https://ivgraph.com/api/notion-graph/"

Como renovar um token expirado:

curl -X POST "https://ivgraph.com/api/auth/refresh/" \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."}'

Resposta:

{"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."}

Sair (adicionar o token de renovação à lista de bloqueio):

curl -X POST "https://ivgraph.com/api/auth/logout/" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"refresh": "<refresh_token>"}'

Endpoints de autenticação

Método	Endpoint	Descrição
GET	/api/integrations/auth/notion/	Iniciar o fluxo OAuth do Notion
GET	/api/integrations/auth/notion/callback	Callback OAuth (interno)
GET	/api/integrations/auth/notion/status	Verificar o status do OAuth
POST	/api/auth/refresh/	Renovar o token de acesso
POST	/api/auth/logout/	Adicionar o token de renovação à lista de bloqueio
GET	/api/auth/validate/	Verificar se o token é válido
GET	/api/auth/me/	Obter informações do usuário atual

Tokens de serviço (para agentes LLM)

Os tokens de serviço oferecem acesso de longa duração, com escopos definidos, à API V1 de somente leitura. São projetados para agentes LLM, scripts de automação e pipelines de CI/CD.

Formato do token

• Prefixo: ivg_ (por exemplo, ivg_a1b2c3d4e5f6...)
• Comprimento: 32 caracteres aleatórios após o prefixo
• Armazenamento: apenas o hash SHA-256 é armazenado no banco de dados — o token em texto puro é exibido uma única vez, na criação

Criar um token

Via API (requer autenticação JWT):

curl -X POST "https://ivgraph.com/api/tokens/" \
  -H "Authorization: Bearer <jwt_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My LLM Agent",
    "scopes": ["graph:search", "graph:read", "graph:neighbors"],
    "workspace_ids": ["your-workspace-uuid"],
    "expires_in_days": 90
  }'

Resposta (o token é exibido apenas uma vez!):

{
  "id": 1,
  "name": "My LLM Agent",
  "token": "ivg_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "prefix": "ivg_a1b2c3",
  "scopes": ["graph:search", "graph:read", "graph:neighbors"],
  "workspace_ids": ["your-workspace-uuid"],
  "is_active": true,
  "created_at": "2026-04-10T12:00:00Z",
  "expires_at": "2026-07-09T12:00:00Z"
}

Escopos

Escopo	Permite
graph:search	Buscar nós pelo título
graph:read	Ler os detalhes do nó e o conteúdo da página
graph:neighbors	Obter nós vizinhos e percorrer caminhos

Limites

• Máximo de 10 tokens por usuário
• Cada token deve ter pelo menos um escopo
• Cada token deve ter pelo menos um workspace_id (acesso negado por padrão)
• Expiração opcional (expires_in_days) — omita para que não expire

Gerenciamento de tokens

Método	Endpoint	Descrição
GET	/api/tokens/	Listar seus tokens (sem os valores em texto puro)
POST	/api/tokens/	Criar um novo token
DELETE	/api/tokens/<id>/	Revogar o token (permanentemente)