Referência da API

Autenticação

Autentique-se na API REST da WASViking com o esquema ApiKey. Bearer é rejeitado silenciosamente.

A API REST pública da WASViking^® usa o esquema de autenticação ApiKey. Os tokens têm o formato wv_live_* para produção e wv_test_* para ambientes de teste.

Authorization: ApiKey wv_live_xxxxxxxxxxxxxxxxxxxx

Importante. O esquema é ApiKey, e não Bearer. Uma requisição com Authorization: Bearer wv_live_… retorna 401 sem corpo. Esta é uma regra rígida e deliberada, não um bug.

Emissão de uma chave

Vá para Settings → API Keys → New key. O portal mostra a chave uma única vez, no momento da criação. Depois disso, a chave é armazenada como hash; o portal só consegue exibir um prefixo e o final mascarado.

Campo	Observações
Name	Identificador legível para o operador (`ci-prod`, `siem-export`).
Scopes	Subconjunto do catálogo de escopos. Prevalece o privilégio mínimo.
Expiration	Opcional. Recomendado para chaves entregues a fornecedores.
IP allow-list	Opcional. Limita de onde a chave pode ser usada.

Escopos (trecho)

Escopo	Permite
`scans:run`	Disparar scans (inclusive via templates).
`scans:read`	Ler status e relatórios de scans.
`findings:read`	Ler achados, evidências e recomendações de IA.
`findings:update`	Transições de status, comentários, atribuição.
`inventory:read`	Ler o Asset Inventory.
`inventory:export`	Exportação em CSV.
`audit_logs:read`	Ler a trilha de auditoria voltada ao cliente.
`sca:submit`	Enviar documentos SBOM a partir do Sentinel.
`sca:read`	Ler o inventário de SBOM e o Supply Chain Watch.
`secrets:submit`	Enviar detecções de secrets a partir do Sentinel.
`templates:read`	Resolver scan templates com escopo da organização pelo slug.
`webhooks:manage`	Criar e rotacionar assinaturas de webhook.
`api_keys:manage`	Emitir e rotacionar chaves de API (por padrão, somente o papel Admin).

A lista completa está em Settings → API Keys → Scopes.

Rate limits

Os rate limits padrão se aplicam por chave:

600 requisições por minuto para endpoints de leitura.
60 requisições por minuto para endpoints de escrita.
12 scans simultâneos disparados via API por organização (configurável).

As respostas que atingem o rate limit retornam 429 com um header Retry-After em segundos.

Erros

Erros comuns:

Status	Significado
`401`	Chave ausente, malformada ou revogada.
`403`	Chave válida, mas sem o escopo necessário.
`404`	O recurso não existe na organização da chave.
`409`	Conflito (por exemplo, o alvo já existe).
`422`	Erro de validação. O corpo é um JSON com os campos que falharam.
`429`	Rate limit atingido.
`5xx`	Erro no lado do servidor. Tente novamente com backoff exponencial.

Schema do corpo de erro:

{
  "error": "rate_limited",
  "message": "API rate limit exceeded. Retry in 30 seconds.",
  "request_id": "req_8fae22c4",
  "details": {}
}

O request_id é registrado em log nos dois lados. Informe-o ao entrar em contato com o suporte.

Rotação de uma chave

No portal: Settings → API Keys → Rotate. A chave antiga continua funcionando por 24 horas (janela de sobreposição), para que você possa atualizar o seu CI sem indisponibilidade. Após 24 horas, a chave antiga é revogada em definitivo.

Para resposta a incidentes, Revoke now (revogar agora) invalida a chave imediatamente.

Exemplo com curl

curl -sS https://api.wasviking.com/v1/findings \
  -H "Authorization: ApiKey ${WASVIKING_API_KEY}" \
  -H "Accept: application/json"

SDKs

Não há SDK oficial no momento. A API é pequena e usa apenas JSON; o seu cliente HTTP padrão é suficiente. Os exemplos das próximas páginas usam curl.

Ambiente de teste

As chaves de teste (wv_test_*) operam contra um ambiente separado, com dados sintéticos. Use-as para builds de SDK e testes de contrato; não misture chaves live e de teste no mesmo pipeline.