Segurança do Projeto

Gerencie chaves JWT, API Keys com scopes e tokens de autenticação para seu módulo.

Visão Geral

Cada projeto na IDE possui seu próprio sistema de segurança isolado, permitindo que você:

Gere chaves JWT secretas para autenticação de usuários
Crie API Keys com permissões específicas (scopes)
Gere tokens JWT para testes e integrações

Isolamento Total

Cada projeto tem suas próprias chaves e tokens. Isso garante que módulos diferentes não compartilhem credenciais de segurança.

JWT Secret — Chave Secreta

A chave JWT é usada para assinar e validar tokens de autenticação. Ela é gerada automaticamente quando você cria um projeto.

Visualizar Chave JWT

Acesse a seção "Segurança" no painel do seu projeto para ver a chave JWT atual.

GET /api/ide/projects/{id}/security

{
  "jwt_secret": "abc123xyz789...",
  "api_keys": [...],
  "module_name": "MeuModulo"
}

Regenerar Chave JWT

Se você suspeitar que sua chave foi comprometida, pode regenerá-la. Atenção: isso invalidará todos os tokens JWT existentes.

POST /api/ide/projects/{id}/security/jwt-secret

{
  "jwt_secret": "nova_chave_gerada...",
  "message": "Chave JWT regenerada. Tokens antigos foram invalidados."
}

Impacto da Regeneração

Ao regenerar a chave JWT, todos os tokens existentes serão invalidados. Usuários precisarão fazer login novamente.

API Keys — Chaves de API

API Keys permitem autenticação sem login de usuário. Cada chave pode ter scopes (permissões) específicos.

Scopes Disponíveis

Scope	Descrição	Exemplo de Uso
`read`	Permite apenas leitura de dados	Consultar produtos, listar usuários
`write`	Permite criar e atualizar dados	Criar pedidos, atualizar perfil
`delete`	Permite deletar dados	Remover produtos, cancelar pedidos
`admin`	Acesso total (inclui read, write, delete)	Operações administrativas

Criar API Key

Você pode criar múltiplas API Keys com diferentes permissões para diferentes integrações.

POST /api/ide/projects/{id}/security/api-key

{
  "label": "Integração Mobile",
  "scopes": ["read", "write"]
}

Resposta

{
  "api_key": "vupi_abc123xyz789...",
  "label": "Integração Mobile",
  "scopes": ["read", "write"],
  "message": "API key gerada. Copie agora — ela não será exibida novamente."
}

Guarde a Chave com Segurança

A API Key completa é exibida apenas uma vez na criação. Guarde-a em um local seguro (variáveis de ambiente, gerenciador de senhas).

Usar API Key nas Requisições

Envie a API Key no header X-API-Key ou Authorization: Bearer:

Exemplo de Requisição

curl -X GET https://api.vupi.us/meumodulo/api/produtos \
  -H "X-API-Key: vupi_abc123xyz789..."

Revogar API Key

Se uma chave foi comprometida ou não é mais necessária, você pode revogá-la:

DELETE /api/ide/projects/{id}/security/api-key/{index}

{
  "message": "API key revogada."
}

Gerar Tokens JWT para Testes

Durante o desenvolvimento, você pode gerar tokens JWT temporários para testar suas rotas protegidas.

POST /api/ide/projects/{id}/security/token

{
  "ttl": 3600,
  "claims": {
    "user_id": "123",
    "role": "admin"
  }
}

Resposta

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "message": "Token JWT gerado para o projeto."
}

Parâmetros

Parâmetro	Tipo	Descrição
`ttl`	integer	Tempo de vida do token em segundos (60 a 2.592.000 — 1 min a 30 dias)
`claims`	object	Dados personalizados a serem incluídos no token (user_id, role, etc.)

Protegendo Rotas com Scopes

Use middlewares para validar scopes nas suas rotas:

Routes/web.php

use Src\Kernel\Middlewares\ApiKeyScopeMiddleware;
use Src\Kernel\Middlewares\RequireWriteScope;
use Src\Kernel\Middlewares\RequireDeleteScope;

// Rota que aceita qualquer API Key válida
$router->get('/api/produtos', [ProdutoController::class, 'list'], [
    ApiKeyScopeMiddleware::class
]);

// Rota que exige scope 'write'
$router->post('/api/produtos', [ProdutoController::class, 'create'], [
    RequireWriteScope::class
]);

// Rota que exige scope 'delete'
$router->delete('/api/produtos/{id}', [ProdutoController::class, 'delete'], [
    RequireDeleteScope::class
]);

Boas Práticas de Segurança

Nunca Exponha Chaves

Não commite chaves JWT ou API Keys no código. Use variáveis de ambiente ou gerenciadores de segredos.

Rotacione Chaves

Regenere chaves periodicamente ou quando houver suspeita de comprometimento.

Princípio do Menor Privilégio

Crie API Keys com apenas os scopes necessários. Evite usar admin quando read é suficiente.

Monitore Uso

Revogue API Keys que não são mais usadas. Mantenha apenas as chaves ativas necessárias.

Próximos Passos

Middlewares de Autenticação

Aprenda a proteger suas rotas com middlewares de autenticação e autorização.

Ver Middlewares

Rotas e Proteção

Entenda como combinar middlewares para criar rotas seguras.

Ver Rotas

Testar Rotas

Use o API Route Tester para testar suas rotas protegidas com tokens e API Keys.

Testar Agora

Conectar App Externa

Integre seu módulo com aplicações externas usando API Keys.

Ver Integração