Guia de início rápido da API

Crie uma conta de serviço e uma chave de API no Developer Hub e, em seguida, faça sua primeira solicitação. Este guia de início rápido usa autenticação por chave de API; não é necessário um cliente OAuth. Consulte Autenticação se sua integração exigir tokens de acesso OAuth de curta duração.

Pré-requisitos

Acesso de administrador ao Painel da Living Security.
O Developer Hub visível em Configurações → Integrações & Developers → Developer Hub.

Criar credenciais

Criar uma conta de serviço

No Developer Hub, abra a guia Service accounts e crie uma conta. Atribua um nome descritivo (por exemplo, reporting-pipeline) e conceda as permissões que suas chaves poderão usar — para este guia, organization:read é suficiente.As permissões da conta são o limite máximo para todas as chaves criadas nela: uma chave nunca pode fazer mais do que a conta de serviço permite.

Criar uma chave de API

Abra a página de detalhes da conta de serviço e crie uma chave. Escolha as permissões de que esta chave específica precisa (um subconjunto das da conta) e uma expiração — 30, 90 ou 365 dias, ou um período personalizado. A expiração é obrigatória.O segredo da chave começa com lsk_live_ e é exibido uma única vez. Copie-o imediatamente para um gerenciador de segredos; ele não poderá ser recuperado depois.

Nunca faça commit de segredos de chaves de API no controle de versão nem os incorpore em código do lado do cliente. Qualquer pessoa que tenha o segredo pode agir com as permissões da chave.

Escolher sua região

Chame o host /v1 regional correspondente à residência de dados da organização. As chaves se autenticam somente nesse host.

Região	URL base
US	`https://api.us-east-1.livingsecurity.ai/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/v1`

Consulte Regiões se você não tiver certeza de qual host usar. Uma chave válida enviada para a outra região falha com unauthorized. Use o menu suspenso de região no exemplo abaixo para alternar o host.

Fazer sua primeira solicitação

Carregue LIVING_SECURITY_API_KEY do seu gerenciador de segredos no ambiente do processo que fará a solicitação. Os exemplos abaixo o leem sem incorporar um segredo ao código-fonte. Para Python, instale requests primeiro.Chame a API com o segredo no campo de senha ou de nome de usuário da autenticação HTTP Basic — qualquer um funciona, de modo que clientes que exigem o preenchimento de ambos os campos (como o conector Web do Power BI) possam colocar um valor provisório como apikey no outro campo.

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

Uma resposta bem-sucedida retorna sua organização:

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

Se você receber essa resposta, suas credenciais funcionam. A solicitação também aparece na guia Request logs do Developer Hub em instantes.

A autenticação Bearer com o mesmo segredo (Authorization: Bearer lsk_live_...) também funciona. A autenticação Basic existe para que ferramentas que só aceitam nome de usuário/senha — como o conector Web do Power BI — possam se conectar.

Como a autenticação funciona

A credencial determina a organização. As solicitações /v1 não contêm seletor de tenant: nem segmento de caminho de organização, nem cabeçalho de organização. O envio de um cabeçalho x-organization-id é rejeitado com invalid_request. O host ainda deve corresponder à região dessa organização. Consulte Regiões.
As permissões são verificadas por operação. Cada operação /v1 exige uma permissão nomeada (por exemplo, GET /v1/organization exige organization:read). Uma chave sem a permissão recebe 403 com o código insufficient_permission.
As chaves expiram e podem ser rotacionadas sem tempo de inatividade. Consulte Chaves de API para saber como fazer a rotação com um período de sobreposição.

Como ler respostas de erro

Todo erro /v1 é application/problem+json (RFC 9457) com um código de máquina estável. Por exemplo, uma solicitação com credencial ausente ou desconhecida retorna:

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

Ramifique a lógica com base em code, nunca em detail. Siga doc_url para ver as etapas de resolução e inclua request_id ao entrar em contato com o suporte — ele corresponde ao cabeçalho de resposta Request-Id e aos logs de solicitações do Developer Hub. O conjunto completo de códigos está na referência de erros.

Versões do contrato

Toda resposta ecoa a versão do contrato que a atendeu no cabeçalho Living-Security-Version, junto com um cabeçalho Request-Id para correlação. Você pode fixar uma solicitação em uma versão publicada do contrato por data:

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

A versão é resolvida nesta ordem: o cabeçalho da solicitação, se presente; caso contrário, o padrão fixado da conta de serviço; caso contrário, a versão publicada mais recente. Solicitar uma versão que não está publicada (ou que passou da data de desativação) retorna 400 com o código unsupported_version. As versões publicadas e suas alterações estão listadas no changelog da API.

Solução de problemas da primeira solicitação

Resultado	Próxima ação
`401 unauthorized`	Verifique o segredo, sua expiração e a região da organização. Não tente outros hosts com uma credencial ativa.
`403 insufficient_permission`	Conceda `organization:read` tanto à conta de serviço quanto à sua chave.
`400 unsupported_version`	Escolha uma versão publicada no changelog.
`429 rate_limited`	Aguarde `Retry-After`; siga o exemplo de nova tentativa limitada.
Tempo limite de rede	Verifique a conectividade e tente novamente esta leitura dentro do orçamento de novas tentativas da sua aplicação.

Para outros erros, siga doc_url da resposta. Guarde Request-Id para o suporte; nunca inclua o cabeçalho Authorization nem sua chave de API em um chamado.

Próximas etapas

Regiões

Escolha o host /v1 dos EUA ou da UE para a organização.

Paginação

Percorra listas com page_token e o envelope de lista.

Limites de taxa

Entenda os orçamentos de solicitações e trate respostas 429.

Referência de erros

Todos os códigos de erro, seu status HTTP e como resolvê-los.

Developer Hub

Gerencie contas de serviço, chaves de API e logs de solicitações.

Central do desenvolvedor

API pública v1

Referência da API v1

Pré-requisitos

Criar credenciais

Como a autenticação funciona

Como ler respostas de erro

Versões do contrato

Solução de problemas da primeira solicitação

Próximas etapas

Regiões

Paginação

Limites de taxa

Referência de erros

Developer Hub

Central do desenvolvedor

API pública v1

Referência da API v1

​Pré-requisitos

​Criar credenciais

​Como a autenticação funciona

​Como ler respostas de erro

​Versões do contrato

​Solução de problemas da primeira solicitação

​Próximas etapas

Regiões

Paginação

Limites de taxa

Referência de erros

Developer Hub

Pré-requisitos

Criar credenciais

Como a autenticação funciona

Como ler respostas de erro

Versões do contrato

Solução de problemas da primeira solicitação

Próximas etapas