Autenticação da API

Autentique com a API REST do sh0 usando tokens JWT Bearer ou chaves API para acesso programático.

Obtendo um Token API

Para obter um token JWT, envie uma requisição POST ao endpoint de login com suas credenciais:

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Se as credenciais forem válidas, a API retorna um token JWT e informações do usuário:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYWJjMTIzIiwiZXhwIjoxNzE...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "name": "Admin",
      "role": "admin"
    }
  }
}

Se a autenticação de dois fatores está habilitada, inclua o código TOTP:

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "totp_code": "123456"
  }'

Autenticação por Token Bearer

Inclua o token JWT no header Authorization de cada requisição API:

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

O token contém o ID do usuário, papel e tempo de expiração. sh0 valida a assinatura e expiração em cada requisição.

export SH0_TOKEN="eyJhbGciOiJIUzI1NiIs..."

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Alternativa com Chave API

Para integrações de longa duração (pipelines CI/CD, scripts de monitoramento, webhooks), chaves API são mais práticas que tokens JWT porque não expiram.

Criando uma chave API:

1. Navegue até Settings → API Keys no dashboard.
2. Clique em Generate API Key.
3. Insira um nome descritivo (ex.: "Pipeline CI/CD" ou "Monitoramento").
4. Copie a chave imediatamente — ela é exibida apenas uma vez.

Usando uma chave API:

curl https://your-server:9000/api/apps \
  -H "X-API-Key: sh0_key_abc123def456"

Expiração & Atualização de Token

Tokens JWT são válidos por 30 dias por padrão. O tempo de expiração é codificado no payload do token.

Para atualizar um token expirando, chame o endpoint de refresh com seu token atual (ainda válido):

curl -X POST https://your-server:9000/api/auth/refresh \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...(new token)...",
    "expires_at": "2026-04-20T12:00:00Z"
  }
}

O dashboard atualiza tokens automaticamente antes de expirarem. Para integrações API, implemente lógica de atualização de token ou use chaves API para evitar problemas de expiração.

Tokens CSRF para Requisições do Dashboard

Ao fazer requisições do dashboard (navegador), sh0 usa tokens CSRF para prevenir ataques de falsificação de requisição entre sites. Isso é tratado automaticamente pelo cliente API do dashboard.

Se você está construindo um frontend personalizado que autentica via cookies (em vez de tokens Bearer), você precisa incluir o token CSRF nas suas requisições:

# Get a CSRF token
curl https://your-server:9000/api/auth/csrf-token \
  -H "Cookie: session=..."

# Include it in state-changing requests
curl -X POST https://your-server:9000/api/apps \
  -H "Cookie: session=..." \
  -H "X-CSRF-Token: csrf_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

Erros de Autenticação

Quando a autenticação falha, a API retorna uma resposta de erro estruturada:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to perform this action"
  }
}

Cenários de erro comuns: