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 a sua primeira solicitação. Este início rápido utiliza autenticação por chave de API; não é necessário um cliente OAuth. Consulte Autenticação caso a sua integração exija 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-lhe um nome descritivo (por exemplo, reporting-pipeline) e conceda as permissões que as respectivas chaves poderão utilizar — para este guia, organization:read é suficiente.As permissões da conta são o limite máximo para todas as chaves criadas sob ela: uma chave nunca pode fazer mais do que a sua 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 necessita (um subconjunto das permissões 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; não será possível recuperá-lo posteriormente.

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 possua o segredo pode agir com as permissões da chave.

Escolher a região

Chame o host /v1 regional que corresponde à 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 caso não tenha certeza de qual host utilizar. Uma chave válida enviada à outra região falha como unauthorized. Use a lista suspensa de região no exemplo abaixo para alternar o host.

Fazer a primeira solicitação

Carregue LIVING_SECURITY_API_KEY a partir do seu gerenciador de segredos no ambiente do processo que realiza a solicitação. Os exemplos abaixo o leem sem incorporar um segredo no código-fonte. Para Python, instale primeiro requests.Chame a API com o segredo no campo de senha ou de nome de usuário da autenticação HTTP Basic — ambos funcionam, de modo que clientes que exigem o preenchimento dos dois campos (como o conector Web do Power BI) podem colocar um marcador 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 a 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ê recebeu esta resposta, as suas credenciais funcionam. A solicitação também aparece na guia Request logs do Developer Hub em alguns instantes.

A autenticação Bearer com o mesmo segredo (Authorization: Bearer lsk_live_...) também funciona. A Basic auth existe para que ferramentas que só utilizam 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: nenhum segmento de caminho de organização e nenhum 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 um 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 uma janela de sobreposição.

Como ler as 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 uma 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
}

Use code como critério de ramificação, nunca detail. Siga doc_url para conhecer 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

Cada resposta repete a versão do contrato que a atendeu no cabeçalho Living-Security-Version, juntamente com um cabeçalho Request-Id para correlação. É possível 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 ultrapassou a data de descontinuação) retorna um 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, a 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 repita 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 a 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, o respectivo 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 as 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 as 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 as respostas de erro

Versões do contrato

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

Próximas etapas