Autenticação

Desenvolvedor

Dica

A autenticação via token de API é o método recomendado para integrações externas. Tokens são vinculados a um workspace específico e oferecem controle granular de acesso.

Métodos de Autenticação

O Prodgy suporta dois métodos de autenticação para acesso a API:

Método	Uso recomendado	Header
Token de API	Integrações externas e automações	X-API-Token: prodgy_...
JWT	Sessões de usuário autenticado	Authorization: Bearer <jwt>

Para integrações externas, utilize sempre tokens de API.

---

Header de Contexto de Organização (Super Admin)

Usuários Super Admin podem sobrescrever o contexto de organização enviando o header X-Organization-Id em qualquer request. Isso permite operar no contexto de uma organização diferente da default do seu perfil.

X-Organization-Id: 6480d1ad-5535-40e1-95b0-05774d3dc4b0

Nota

Este header é respeitado apenas para usuários Super Admin. Para roles Admin e User regulares, ele é ignorado — a organização é sempre determinada pelo token JWT.

O header deve conter um UUID válido. Ele é injetado automaticamente pelo frontend do Prodgy quando um Super Admin seleciona uma organização no dropdown da sidebar.

---

Token de API

Formato

Os tokens seguem o formato:

prodgy_<caracteres_aleatórios>

Exemplo: prodgy_k8d9Jf2kL9mP3qR4sT5uV6wX7yZ8aB9c

Como Enviar o Token

Inclua o token em uma das seguintes formas no header da requisição:

X-API-Token: prodgy_k8d9Jf2kL9mP3qR4sT5uV6wX7yZ8aB9c

ou

Authorization: Bearer prodgy_k8d9Jf2kL9mP3qR4sT5uV6wX7yZ8aB9c

Exemplo com cURL

curl -X GET https://<instância>/api/agent-base/product/<product_id> \
  -H "X-API-Token: prodgy_k8d9Jf2kL9mP3qR4sT5uV6wX7yZ8aB9c"

---

Endpoints Disponíveis

Os seguintes endpoints são acessíveis via Token de API, agrupados por categoria:

Agent Base

Endpoint	Métodos	Descrição
/api/agent-base	GET, POST, DELETE	Listar, instalar e desinstalar agentes de um workspace
/api/agent-base/{id}/executions	GET	Listar execuções de um agente específico
/api/agent-base/triggers	GET, POST	Listar e executar triggers manuais

Executor de Workflows

Endpoint	Métodos	Descrição
/api/workflow/execute	POST	Executar um teste de workflow
/api/workflow/{executionId}/status	GET	Obter status da execução
/api/workflow/{executionId}/events	GET	Stream de eventos da execução (SSE)
/api/workflow/{executionId}/stop	POST	Parar uma execução em andamento
/api/workflow/{executionId}/pause	POST	Pausar uma execução em andamento
/api/workflow/{executionId}/continue	POST	Retomar uma execução pausada

Workflow Base

Endpoint	Métodos	Descrição
/api/workflow-base	GET, POST, PUT, DELETE	Gerenciar definições de workflow base

Executor de Nodes

Endpoint	Métodos	Descrição
/api/nodes/execute	POST	Executar um node individual
/api/nodes/status/{nodeId}	GET	Obter status da execução do node

Integrations Base

Endpoint	Métodos	Descrição
/api/integrations-base	GET, POST, PUT, DELETE	Gerenciar configurações de integrações
/api/external/integrations	GET	Listar integrações ativas da organização

Knowledge Base

Endpoint	Métodos	Descrição
/api/knowledge-base/{productId}	GET	Listar bases de conhecimento de um workspace
/api/knowledge-base/embeddings	GET, POST, PUT, DELETE	Gerenciar embeddings e busca semântica
/api/knowledge-base/storage	GET, POST, PUT, DELETE	Upload, download e gerenciamento de arquivos

Assistente

Endpoint	Métodos	Descrição
/api/assistant/chat	POST	Enviar mensagem e receber resposta da IA (streaming)
/api/assistant/chat/history	GET	Recuperar histórico de sessão de chat

Tokens de API

Endpoint	Métodos	Descrição
/api/api-token/auth/validate	GET	Validar o token de API atual

Nota

Os endpoints de gerenciamento de agentes (CRUD) e workflows (CRUD) não são acessíveis via Token de API. Eles requerem autenticação interna (JWT ou token de serviço do backend).

Dica

Para detalhes completos dos endpoints, schemas de request/response e testes ao vivo, acesse a documentação interativa do Swagger em https://<seu-host-api>/swagger.

---

Criando um Token

Tokens são criados pela interface do Prodgy ou via API (com autenticação JWT).

Via Interface

1. Acesse as configurações do workspace (botão de engrenagem na navbar)
2. Clique na aba Tokens de API
3. Clique em Criar Token
4. Informe o nome e, opcionalmente, uma data de expiração
5. Copie o token gerado — ele é exibido apenas uma vez

Via API

POST /api/api-tokens
Content-Type: application/json
Authorization: Bearer <jwt_token>

{
  "product_id": "644c3604-4fd3-4681-846b-8ae14f18f00d",
  "token_name": "Minha Integração",
  "expires_at": "2026-12-31T23:59:59Z"
}

Resposta (201):

{
  "success": true,
  "message": "API token created successfully",
  "data": {
    "id": "uuid",
    "token": "prodgy_...",
    "token_name": "Minha Integração",
    "token_prefix": "prodgy_k8...",
    "product_id": "644c3604-...",
    "expires_at": "2026-12-31T23:59:59Z",
    "created_at": "2026-03-05T10:00:00Z"
  }
}

Cuidado

O token completo é exibido apenas uma vez na criação. Após fechar o diálogo ou a resposta da API, somente o prefixo estará disponível. Armazene o token em local seguro.

---

Validando um Token

Para verificar se um token é válido:

GET /api/api-token/auth/validate
X-API-Token: prodgy_<token>

Resposta (200) — Token válido:

{
  "success": true,
  "authType": "api_token",
  "userId": "uuid",
  "productId": "uuid",
  "organizationId": "uuid",
  "apiTokenId": "uuid"
}

Resposta (401) — Token inválido:

{
  "error": "Unauthorized",
  "message": "Invalid API token"
}

---

Gerenciando Tokens via API

Listar Tokens do Workspace

GET /api/api-tokens/product/{productId}
Authorization: Bearer <jwt_token>

Atualizar Token

PUT /api/api-tokens/{id}
Content-Type: application/json
Authorization: Bearer <jwt_token>

{
  "token_name": "Novo Nome",
  "is_active": true,
  "expires_at": "2027-06-30T23:59:59Z"
}

Revogar Token

POST /api/api-tokens/{id}/revoke
Authorization: Bearer <jwt_token>

Renovar Expiração

POST /api/api-tokens/{id}/renew
Content-Type: application/json
Authorization: Bearer <jwt_token>

{
  "expires_at": "2027-12-31T23:59:59Z"
}

Regenerar Token

POST /api/api-tokens/{id}/regenerate
Authorization: Bearer <jwt_token>

Nota

Ao regenerar, um novo token é criado é o anterior e arquivado. O novo token é exibido apenas uma vez na resposta.

Excluir Token

DELETE /api/api-tokens/{id}
Authorization: Bearer <jwt_token>

---

Logs de Auditoria

Cada uso de token é registrado automaticamente. Para consultar os logs:

GET /api/api-tokens/{id}/audit-logs?limit=100
Authorization: Bearer <jwt_token>

Resposta:

{
  "success": true,
  "data": [
    {
      "action": "used",
      "ip_address": "192.168.1.100",
      "user_agent": "curl/7.88.0",
      "endpoint": "/api/agent-base/product/...",
      "status_code": 200,
      "created_at": "2026-03-05T14:30:00Z"
    }
  ]
}

Tipos de Ação Registrados

Ação	Descrição
created	Token foi criado
used	Token foi utilizado em uma requisição
revoked	Token foi revogado
expired	Token expirou
renewed	Expiração do token foi estendida
regenerated	Novo token foi gerado a partir do anterior

---

Boas Práticas

• Utilize HTTPS em todas as requisições em produção
• Nunca exponha tokens em repositórios de código ou logs públicos
• Configure datas de expiração para tokens temporários
• Rotacione tokens periodicamente usando a função de regenerar
• Monitore os logs de auditoria para detectar acessos suspeitos
• Utilize um token por integração para facilitar o rastreamento