Gestão de conta e cadastro

Esta página cobre o ciclo completo de gestão de conta para a API do vario: desde o cadastro inicial até a rotação de credenciais. Todos os exemplos usam a URL base de produção https://api.vario.lat.

1. Cadastro de conta de API

`POST /api/public/api-signup`

Cria uma conta API-only com 250 créditos de teste gratuitos. Não requer autenticação prévia. Após a criação da conta, a API key também é enviada por e-mail.

Autenticação: nenhuma (endpoint público, com rate limit de 5 requisições/min).

Parâmetros da requisição:

Campo	Tipo	Obrigatório	Descrição
`email`	`string`	Sim	E-mail corporativo. Domínios de e-mail gratuito não são aceitos.
`name`	`string`	Sim	Nome completo do solicitante.
`organization`	`string`	Sim	Nome da organização.

Exemplo de requisição:

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Ana Beatriz Souza",
    "organization": "Escritório Forense LATAM"
  }'

Exemplo de resposta 201:

{
  "api_key": "vario_xbGhABC123...WXYZ",
  "credits_balance": 250,
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced."
}

ℹ

Importante: a api_key é exibida apenas uma vez nesta resposta. Guarde-a imediatamente em um gerenciador de segredos. O vario não armazena o valor completo da key — se você a perder, precisará revogá-la e gerar uma nova.

Erros possíveis:

HTTP	Código	Condição
`409`	`email_already_registered`	O e-mail já possui uma conta registrada.
`422`	`VALIDATION_ERROR`	E-mail de domínio gratuito, formato inválido ou campo ausente.
`429`	`RATE_LIMIT_EXCEEDED`	Foram excedidas 5 requisições por minuto.

2. Informações da conta

`GET /api/v1/api-portal/me`

Retorna o estado atual da conta: identidade, tipo de conta, status da assinatura e saldo de créditos.

Autenticação: Authorization: Bearer vario_SUA_API_KEY ou SSO (sessão do portal web).

Exemplo de requisição:

curl https://api.vario.lat/api/v1/api-portal/me \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Exemplo de resposta 200:

{
  "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "name": "Ana Beatriz Souza",
  "organization": "Escritório Forense LATAM",
  "account_type": "api_only",
  "subscription_status": "trial",
  "credits_balance": 247,
  "api_keys_count": 1
}

Campos da resposta:

Campo	Tipo	Descrição
`tenant_id`	`string` (UUID)	Identificador único do tenant. Imutável.
`email`	`string`	E-mail associado à conta.
`name`	`string`	Nome do titular da conta.
`organization`	`string`	Nome da organização cadastrada.
`account_type`	`string`	`"api_only"` para contas sem seats. `"saas"` para contas com assinatura SaaS.
`subscription_status`	`string`	`"trial"` / `"active"` / `"past_due"` / `"canceled"`.
`credits_balance`	`integer`	Créditos disponíveis no saldo atual.
`api_keys_count`	`integer`	Número de API keys ativas associadas à conta.

3. Listar API keys

`GET /api/v1/api-portal/keys`

Retorna todas as API keys ativas da conta. O valor completo de cada key não está incluído na resposta — apenas um key_hint é exibido para identificação visual.

Autenticação: Authorization: Bearer vario_SUA_API_KEY ou SSO.

Exemplo de requisição:

curl https://api.vario.lat/api/v1/api-portal/keys \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Exemplo de resposta 200:

[
  {
    "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Produção — CADE matter 2026",
    "key_hint": "vario_xbGh...WXYZ",
    "scopes": ["analyze:run", "playbooks:list"],
    "is_active": true,
    "last_used_at": "2026-06-01T18:45:00Z",
    "created_at": "2026-05-15T10:00:00Z",
    "expires_at": null
  },
  {
    "key_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "CI pipeline",
    "key_hint": "vario_yZaB...VWXY",
    "scopes": ["analyze:run"],
    "is_active": true,
    "last_used_at": "2026-06-02T08:12:00Z",
    "created_at": "2026-05-20T14:30:00Z",
    "expires_at": "2027-05-20T00:00:00Z"
  }
]

Campos da resposta:

Campo	Tipo	Descrição
`key_id`	`string` (UUID)	Identificador único da key. Usado para revogá-la.
`name`	`string`	Rótulo descritivo atribuído ao criar a key.
`key_hint`	`string`	Primeiros 10 e últimos 4 caracteres do token. Apenas para identificação visual.
`scopes`	`list[string]`	Permissões habilitadas nessa key.
`is_active`	`boolean`	`false` se a key foi revogada.
`last_used_at`	`string` (ISO 8601)	Última vez que essa key realizou uma requisição bem-sucedida. `null` se nunca foi usada.
`created_at`	`string` (ISO 8601)	Data de criação.
`expires_at`	`string` (ISO 8601) \| `null`	Data de expiração configurada, ou `null` se não expirar.

4. Criar API key adicional

`POST /api/v1/api-portal/keys`

Gera uma nova API key para a conta. Disponível apenas via SSO (sessão ativa no portal web) — não pode ser invocado usando uma API key existente como credencial.

Autenticação: SSO (sessão ativa no portal web).

Parâmetros da requisição:

Campo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Rótulo para identificar esta key.
`scopes`	`list[string]`	Não	Valores válidos: `"analyze:run"`, `"playbooks:list"`. Padrão: todos.
`expires_at`	`string` (ISO 8601)	Não	Data de expiração. Se omitido, a key não expira.

Exemplo de resposta 201:

{
  "key_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "key": "vario_newXYZ789...ABCD",
  "name": "CI pipeline",
  "scopes": ["analyze:run"],
  "expires_at": "2027-06-01T00:00:00Z",
  "created_at": "2026-06-02T10:00:00Z",
  "warning": "Store this key immediately. It will not be shown again."
}

5. Revogar API key

`DELETE /api/v1/api-portal/keys/{key_id}`

Revoga uma API key de forma permanente e imediata.

Autenticação: Authorization: Bearer vario_SUA_API_KEY ou SSO.

curl -X DELETE https://api.vario.lat/api/v1/api-portal/keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Resposta 204 No Content — sem corpo.

ℹ

Efeito imediato: não há período de carência. Qualquer requisição autenticada com a key revogada falha com 401 a partir do momento da revogação.

6. Rotação rápida de API key

`POST /api/public/api-keys/rotate`

Invalida a API key atual e gera uma nova com os mesmos escopos em uma única operação. Projetado para resposta a incidentes de segurança.

curl -X POST https://api.vario.lat/api/public/api-keys/rotate \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Exemplo de resposta 200:

{
  "key": "vario_newABC123...WXYZ",
  "key_hint": "vario_newABC...WXYZ",
  "warning": "Store immediately — not shown again. The previous key is now invalid."
}

ℹ

Sequência de rotação recomendada:

Executar POST /api/public/api-keys/rotate.
Salvar a nova key imediatamente.
Atualizar a variável de ambiente em todos os serviços que usavam a key anterior.
Verificar que os serviços respondem corretamente com a nova key.

Boas práticas de gestão de credenciais

Nunca incluir a API key no código-fonte. Usar variáveis de ambiente ou um gerenciador de segredos.
Uma key por ambiente. Criar keys separadas para desenvolvimento, staging e produção.
Usar name descritivo. Facilita identificar qual serviço usa cada key.
Configurar expires_at para keys de curta duração. Útil para integrações temporárias.
Diante de suspeita de comprometimento: usar POST /api/public/api-keys/rotate imediatamente.

Fluxo completo de onboarding

# Passo 1: Cadastrar conta e obter a key inicial
curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Ana Beatriz Souza",
    "organization": "Escritório Forense LATAM"
  }'

# Saldo inicial: 250 créditos de teste

# Passo 2: Verificar a conta
curl https://api.vario.lat/api/v1/api-portal/me \
  -H "Authorization: Bearer vario_SUA_API_KEY"

# Passo 3: Ver as keys ativas
curl https://api.vario.lat/api/v1/api-portal/keys \
  -H "Authorization: Bearer vario_SUA_API_KEY"