Autenticação

A API do Lumina Flow Builder usa autenticação baseada em API Keys para garantir acesso seguro aos recursos.

Visão Geral

Todas as requisições à API devem incluir uma API Key válida no header Authorization:

Authorization: Bearer YOUR_API_KEY

Obtendo sua API Key

1. Acesse o Dashboard

Faça login no dashboard do Lumina com suas credenciais.

2. Navegue até Configurações

No menu lateral, clique em Configurações → API Keys.

3. Crie uma Nova API Key

Clique em "Nova API Key"
Defina um nome descritivo (ex: "Produção", "Desenvolvimento")
Configure permissões (opcional)
Clique em "Gerar"

4. Copie e Armazene com Segurança

⚠️ IMPORTANTE: A API Key será exibida apenas uma vez. Copie e armazene em local seguro.

lumina_sk_1234567890abcdef1234567890abcdef

Tipos de API Keys

Production Keys

Prefixo: lumina_sk_

Acesso completo aos recursos de produção
Rate limits padrão do seu plano
Logs completos de auditoria

Test Keys

Prefixo: lumina_test_sk_

Ambiente de testes isolado
Rate limits reduzidos
Não afeta dados de produção

Usando a API Key

cURL

curl -X GET https://api.lumina.app.br/v1/flows \
  -H "Authorization: Bearer lumina_sk_1234567890abcdef"

JavaScript / Node.js

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://api.lumina.app.br/v1',
  headers: {
    'Authorization': `Bearer ${process.env.LUMINA_API_KEY}`
  }
});

// Fazer requisição
api.get('/flows')
  .then(response => console.log(response.data))
  .catch(error => console.error(error.response.data));

Python

import requests
import os

API_KEY = os.environ.get('LUMINA_API_KEY')
BASE_URL = 'https://api.lumina.app.br/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}'
}

response = requests.get(f'{BASE_URL}/flows', headers=headers)
print(response.json())

PHP

<?php
$api_key = getenv('LUMINA_API_KEY');
$base_url = 'https://api.lumina.app.br/v1';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$base_url/flows");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

Go

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("LUMINA_API_KEY")
    baseURL := "https://api.lumina.app.br/v1"

    client := &http.Client{}
    req, _ := http.NewRequest("GET", baseURL+"/flows", nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // Processar resposta...
}

Permissões e Escopos

Ao criar uma API Key, você pode definir permissões granulares:

Escopos Disponíveis

Escopo	Descrição	Operações
`flows:read`	Ler flows	GET /flows
`flows:write`	Criar/atualizar flows	POST, PATCH /flows
`flows:delete`	Deletar flows	DELETE /flows
`flows:execute`	Executar flows	POST /flows/:id/execute
`executions:read`	Ler execuções	GET /executions
`executions:write`	Gerenciar execuções	POST, PATCH /executions
`webhooks:read`	Ler webhooks	GET /webhooks
`webhooks:write`	Criar/gerenciar webhooks	POST, PATCH, DELETE /webhooks
`admin:*`	Acesso administrativo completo	Todas as operações

Exemplo de Configuração

{
  "name": "API Key de Produção",
  "scopes": [
    "flows:read",
    "flows:execute",
    "executions:read"
  ],
  "expiresAt": "2025-12-31T23:59:59Z"
}

Segurança

Boas Práticas

1. Nunca Exponha suas API Keys

❌ NUNCA faça isso:

// Hard-coded no código
const apiKey = 'lumina_sk_1234567890abcdef';

// Comitado no Git
API_KEY=lumina_sk_1234567890abcdef

// No frontend
<script>
  const apiKey = 'lumina_sk_1234567890abcdef';
</script>

✅ Faça isso:

// Variáveis de ambiente
const apiKey = process.env.LUMINA_API_KEY;

// Secrets no CI/CD
// Configurado no GitHub Actions, GitLab CI, etc.

// Backend apenas
// API keys devem ficar APENAS no servidor

2. Use Variáveis de Ambiente

.env

LUMINA_API_KEY=lumina_sk_1234567890abcdef
LUMINA_API_URL=https://api.lumina.app.br/v1

.gitignore

.env
.env.local
.env.*.local

Carregando no código:

// Node.js com dotenv
require('dotenv').config();
const apiKey = process.env.LUMINA_API_KEY;

3. Rotacione API Keys Regularmente

Rotacione keys a cada 90 dias
Rotacione imediatamente se houver suspeita de exposição
Mantenha múltiplas keys para rotação sem downtime

4. Use API Keys Específicas por Ambiente

Desenvolvimento: lumina_test_sk_dev_...
Staging: lumina_test_sk_staging_...
Produção: lumina_sk_prod_...

5. Restrinja Permissões

Conceda apenas os escopos necessários:

// Key para apenas executar flows
scopes: ['flows:execute', 'executions:read']

// Key para leitura apenas
scopes: ['flows:read', 'executions:read']

6. Configure IP Whitelist

No dashboard, configure IPs permitidos:

192.168.1.100
10.0.0.0/8

Revogando API Keys

Se uma API Key foi exposta:

Acesse Configurações → API Keys
Encontre a key comprometida
Clique em "Revogar"
Gere uma nova key
Atualize suas aplicações

Requisições com keys revogadas receberão erro 401:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key inválida ou revogada"
  }
}

Erros de Autenticação

401 Unauthorized

API Key ausente, inválida ou revogada.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API Key inválida"
  }
}

Soluções: - Verifique se o header Authorization está presente - Confirme se a API Key está correta - Verifique se a key não foi revogada

403 Forbidden

API Key válida mas sem permissão para a operação.

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Sem permissão para esta operação",
    "details": {
      "requiredScope": "flows:delete",
      "currentScopes": ["flows:read", "flows:execute"]
    }
  }
}

Soluções: - Verifique os escopos da sua API Key - Use uma key com permissões adequadas - Solicite acesso adicional ao administrador

Autenticação com Webhooks

Para webhooks, use assinaturas HMAC para validar a origem:

Validando Webhooks

const crypto = require('crypto');

function validateWebhook(req) {
  const signature = req.headers['x-lumina-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');

  return signature === hash;
}

// Uso
app.post('/webhook', (req, res) => {
  if (!validateWebhook(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Processar webhook...
  res.json({ received: true });
});

Monitoramento

Logs de Acesso

Todos os acessos à API são registrados:

{
  "timestamp": "2025-01-15T10:30:00Z",
  "apiKey": "lumina_sk_...abcd",
  "ip": "192.168.1.100",
  "method": "GET",
  "endpoint": "/flows",
  "status": 200,
  "duration": 45
}

Alertas

Configure alertas para: - Uso anormal de API Keys - Múltiplas tentativas de autenticação falhadas - Acessos de IPs não autorizados

Limitações

Rate Limits por API Key

Limites são aplicados por API Key:

Plano	Limite por Hora	Burst
Free	100	10/min
Pro	1,000	50/min
Enterprise	10,000	200/min

Expiração

API Keys podem ter data de expiração configurável:

{
  "expiresAt": "2025-12-31T23:59:59Z"
}

Migrando para Nova API Key

Para migrar sem downtime:

Crie nova API Key
Atualize aplicações gradualmente
Monitore uso da antiga key
Revogue antiga key quando uso chegar a zero

# Exemplo de rollout gradual
# 1. Deploy com nova key em 10% dos servidores
# 2. Monitore por 24h
# 3. Deploy para 50%
# 4. Monitore por 24h
# 5. Deploy para 100%
# 6. Revogue antiga key

FAQ

Posso usar a mesma API Key em múltiplos servidores?

Sim, mas é recomendado usar keys diferentes para facilitar auditoria e revogação.

Como funciona o rate limiting?

Rate limiting é aplicado por API Key. Requisições de diferentes keys não afetam umas às outras.

API Keys expiram automaticamente?

Apenas se você configurar uma data de expiração. Por padrão, keys não expiram.

Posso recuperar uma API Key revogada?

Não. Você deve criar uma nova API Key.

Próximos Passos

← API | Flows API →