T2Mark Docs
Painel
Docs / API Reference / Autenticação

Autenticação

A API do T2Mark usa dois mecanismos de autenticação dependendo da fase do agente:

  1. TenantKey → Primeira vez (registro)
  2. ApiKey → Depois (todas as operações)

Este guia explica como cada um funciona e como integrar.

Fase 1: TenantKey (Registro Inicial)

O Que É

A TenantKey identifica sua empresa/tenant no T2Mark.

Onde Encontrar

No Painel T2Mark:

  1. Vá a “Agente Windows” → “Download”
  2. Você vê: “Seu TenantKey: tk_a1b2c3d4e5f6...”
  3. Também está embutido no T2Mark-Setup.exe

Formato

tk_a1b2c3d4e5f6ghijklmnop1234567890abcdef
Parte Significado
tk_ Prefixo (identifica como TenantKey)
Resto 38 caracteres aleatórios (base62)

Uso: POST /api/register

Ao registrar, envie a TenantKey:

curl -X POST https://t2mark.setor9.net/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "tenantKey": "tk_a1b2c3d4e5f6ghijklmnop1234567890abcdef",
    "hostname": "PC-VENDAS-001",
    "hwid": "550e8400e29b41d4a716446655440000"
  }'

Resposta

{
  "status": "registered",
  "apiKey": "ak_5f1b3c8e9d2a4b6c7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
  "machineId": 42
}

Importante: A apiKey é retornada apenas uma vez. O agente deve salvá-la em config.ini.

Fase 2: ApiKey (Operações Autenticadas)

O Que É

A ApiKey identifica uma máquina específica após registro.

Formato

ak_5f1b3c8e9d2a4b6c7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b
Parte Significado
ak_ Prefixo (identifica como ApiKey)
Resto 64 caracteres hexadecimais (hash SHA-256)

Armazenamento no Servidor

Servidor recebe: ak_5f1b3c8e9d2a4b6c7e8f...
Servidor armazena: SHA-256(ak_5f1b3c8e9d2a4b6c7e8f...)
Servidor compara: SHA-256(chave_enviada) == SHA-256_armazenado

Benefício: Se banco de dados for comprometido, ApiKey original não é exposta.

Onde Está Armazenada

Na máquina do agente:

C:\T2Mark\config.ini

[Agent]
ApiKey=ak_5f1b3c8e9d2a4b6c7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b

Como Usar ApiKey em Requisições

Envie a ApiKey no header X-API-Key:

curl -X GET https://t2mark.setor9.net/api/policy \
  -H "X-API-Key: ak_5f1b3c8e9d2a4b6c7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b"

Headers Obrigatórios

Header Valor Exemplo
X-API-Key ApiKey da máquina ak_5f1b3c...
Content-Type (se houver corpo) application/json

Exemplo Completo: GET /api/policy

curl -X GET https://t2mark.setor9.net/api/policy \
  -H "X-API-Key: ak_5f1b3c8e9d2a4b6c7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b" \
  -H "User-Agent: T2Mark-Agent/1.0" \
  -H "Accept: application/json"

Fluxo Completo: Do Primeiro Uso à Operação

┌─ PRIMEIRA VEZ ─────────────────────────────────────┐
│                                                     │
│ 1. Admin cria conta T2Mark                         │
│    ↓ Recebe TenantKey (gerado automaticamente)     │
│                                                     │
│ 2. Admin baixa instalador T2Mark-Setup.exe         │
│    ↓ Instalador contém TenantKey embutida         │
│                                                     │
│ 3. Usuário executa instalador                      │
│    ↓ Agente começa, faz POST /api/register        │
│    ↓ Envia TenantKey                              │
│                                                     │
│ 4. Servidor valida TenantKey                       │
│    ↓ Cria registro da máquina                      │
│    ↓ Gera ApiKey aleatória (64 chars)             │
│    ↓ Armazena SHA-256(ApiKey) no banco            │
│    ↓ Retorna ApiKey em texto plano (única vez)   │
│                                                     │
│ 5. Agente recebe ApiKey                            │
│    ↓ Salva em C:\T2Mark\config.ini                │
│    ↓ Deleta TenantKey (não precisa mais)          │
│                                                     │
└─────────────────────────────────────────────────────┘

┌─ OPERAÇÕES NORMAIS ────────────────────────────────┐
│                                                     │
│ 6. Agente faz polling:                            │
│    GET /api/policy                                 │
│    Header: X-API-Key: ak_5f1b3c...               │
│    ↓ Servidor valida ApiKey (compara hash)        │
│    ↓ Retorna política atual                       │
│                                                     │
│ 7. Agente envia heartbeat:                        │
│    POST /api/heartbeat                            │
│    Header: X-API-Key: ak_5f1b3c...               │
│    ↓ Servidor marca máquina como "online"        │
│                                                     │
│ 8. Agente se desinstala:                          │
│    POST /api/unregister                           │
│    Header: X-API-Key: ak_5f1b3c...               │
│    ↓ Servidor revoga ApiKey                       │
│    ↓ Remove máquina da lista                      │
│                                                     │
└─────────────────────────────────────────────────────┘

Validação de Autenticação

O Que o Servidor Valida

  1. ✅ ApiKey presente? (X-API-Key header)
  2. ✅ Formato válido? (começa com ak_?)
  3. ✅ Existe no banco? (SHA-256 match)
  4. ✅ Máquina está ativa? (não desativada)
  5. ✅ Tenant está ativo? (assinatura válida)

Ordem de Validação

Requisição HTTP
    ↓
Header X-API-Key presente?
    ↓ Não → 401 Unauthorized
    ↓ Sim
Formato válido (ak_...)?
    ↓ Não → 400 Bad Request
    ↓ Sim
SHA-256(apikey) no banco?
    ↓ Não → 401 Unauthorized
    ↓ Sim
Máquina ativa?
    ↓ Não → 403 Forbidden (machine blocked)
    ↓ Sim
Tenant ativo?
    ↓ Não → 403 Forbidden (tenant disabled)
    ↓ Sim
✓ Autorizado — Processa requisição

Respostas de Erro

401 Unauthorized

Causa: ApiKey ausente, inválido ou revogado

Exemplos:
- Máquina fez unregister (ApiKey foi revogado)
- ApiKey está corrompido em config.ini
- Máquina foi desinstalada e reinstalada (novo ApiKey gerado)
- Máquina registrada em outro tenant

Resposta:
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Causa: Autenticação OK, mas permissão negada

Exemplos:
- Máquina está desativada (admin desativou no painel)
- Tenant está desativado (assinatura expirou)
- Máquina foi bloqueada (muito spam/tentativas erradas)

Resposta:
{
  "error": "Forbidden",
  "message": "Machine or tenant is disabled"
}

409 Conflict

Causa: Máquina já registrada (ao tentar registrar novamente)

Exemplos:
- Mesmo HWID já foi registrado antes
- Agente tenta registrar sem verificar se já existe

Resposta (em POST /api/register):
{
  "status": "reactivated",
  "apiKey": "ak_novo_hash...",
  "machineId": 42
}

(Gera nova ApiKey, revoga a anterior)

Segurança: Boas Práticas

✅ Recomendado

❌ Evite

Regenerar ApiKey (Emergência)

Se suspeitar que a ApiKey foi comprometida:

No painel:

  1. Vá a “Máquinas”
  2. Encontre a máquina
  3. Clique [Regenerar ApiKey]
  4. Nova chave é gerada
  5. Máquina faz re-registro automaticamente
  6. Antiga é revogada

Na máquina:

# Opção 1: Reinstalar agente (recebe novo ApiKey)
Core.exe -uninstall
# Baixe e instale novamente

# Opção 2: Aguardar pool de re-registro
# Agente verifica a cada 24h se precisa re-registrar

Resumo Rápido

TENANTKEY:
  - Primeira vez (registro)
  - No instalador
  - Identifica empresa
  - Descartado após uso

APIKEY:
  - Depois do registro
  - Em config.ini
  - Identifica máquina
  - Usado em todas as operações
  - Enviado em: X-API-Key header

FLUXO:
  1. POST /api/register (envia TenantKey)
  2. Recebe ApiKey
  3. Armazena em config.ini
  4. Usa X-API-Key: ak_... em todas as requisições

ERROS:
  401 → ApiKey inválido/ausente
  403 → Máquina/tenant desativado
  409 → Máquina já registrada