API Pública Legada

Este guia aborda as integrações /api/v1 existentes que trocam uma chave de acesso da API por um token de portador (bearer token). Suas credenciais e o formato das solicitações diferem da API Pública /v1. Para uma nova integração, comece com o guia de início rápido da API e com Autenticação. A nova API /v1 usa chaves de API de conta de serviço ou tokens de acesso OAuth.

Antes de começar

Você precisa de:

Acesso ao Living Security que permita o gerenciamento de chaves de acesso da API
Uma chave de acesso da API criada em Configurações → Access Keys
O segredo da chave de acesso, exibido uma única vez quando a credencial é criada
O ID do emissor da API, fornecido pela Living Security junto com as suas credenciais da API Pública
A URL base regional da organização que você está integrando
Um ambiente de execução no lado do servidor e um gerenciador de segredos

Os segredos das chaves de acesso não devem ser colocados em código de navegador, aplicativos móveis, controle de versão, variáveis de ambiente do lado do cliente, tickets ou logs compartilhados.

A caixa de diálogo Access Keys exibe o segredo uma única vez, mas não exibe o ID do emissor da API. Se a Living Security não tiver fornecido o ID do emissor junto com as suas credenciais da API Pública, solicite-o ao Suporte da Living Security. O ID do emissor não é o ID da chave de acesso nem o ID da organização.

Hosts regionais

O contrato legado usa estes hosts regionais de produção /api/v1:

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

Use a região atribuída à organização na Living Security. Não troque de região para contornar um erro de autorização ou de disponibilidade.

Recursos legados

Recurso	Operações compatíveis
Pessoas	Pesquisar pessoas da organização e recuperar a associação de uma pessoa
Chaves de acesso da API	Criar, listar, rotacionar e revogar chaves de acesso da API

Use Developers → Public API Reference para consultar a lista completa de operações, parâmetros, solicitações, respostas e esquemas. Se uma operação não estiver lá, ela não faz parte atualmente da API Pública.

Autenticação

O acesso à API Pública tem duas etapas:

Troque o segredo da chave de acesso e o ID do emissor da API por um token de portador de curta duração e um ID de organização.
Envie o token de portador e o ID da organização em cada solicitação à API.

Os cabeçalhos de solicitação obrigatórios são:

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

O cabeçalho da organização deve conter a organização retornada pela troca da chave de acesso. Uma chave não autoriza o acesso a um ID de organização arbitrário.

SDK TypeScript

Instale a versão principal atual:

npm install @livingsecurity/sdk@^1

Em seguida, troque a chave e configure o SDK:

import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});

Use a URL base da UE para uma organização da UE. A troca pelo SDK destina-se a ambientes de execução Node.js no lado do servidor.

Solicitação REST direta

Se você realizar a troca fora do SDK, envie o token de portador e o ID da organização em todas as solicitações:

curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"

Os tokens de portador têm curta duração. Realize novamente a troca da chave de acesso ao obter um novo token, em vez de manter um token de portador como credencial permanente.

Ciclo de vida da chave de acesso

Nomeie as chaves de acordo com a integração ou automação responsável por elas.
Escolha os escopos de menor privilégio oferecidos pelo formulário de chave de acesso.
Armazene o segredo exibido uma única vez imediatamente; ele não pode ser recuperado após a criação ou a rotação.
Rotacione uma chave em Configurações → Access Keys e implante a substituta antes de revogar a credencial antiga.
Revogue as chaves que não são mais usadas ou cujo segredo possa ter sido exposto.
Use chaves de conta de serviço para integrações não humanas quando esse tipo de chave estiver disponível para a sua organização.

Paginação

A pesquisa de pessoas é compatível com os parâmetros limit, cursor, offset e includeTotal. Prefira o cursor retornado pela resposta anterior para percorrer os resultados sequencialmente.

limit tem valor padrão 50 e aceita de 1 a 100.
cursor continua a partir de uma resposta anterior.
offset ignora um número de registros e tem valor padrão 0.
includeTotal=true solicita uma contagem filtrada exata; omita-o quando a contagem não for necessária.

Leia o objeto pagination retornado pelo endpoint. Não calcule a próxima página com base no número de linhas recebidas nem combine solicitações paginadas de forma independente para depois ordenar você mesmo os resultados parciais.

Erros

Os erros JSON documentados usam este formato geral:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

message pode ser uma string ou uma matriz de mensagens de validação.

Status	Significado	Resposta
`400`	Parâmetros ou corpo da solicitação inválidos	Corrija os erros de validação indicados
`401`	O token de portador está ausente, é inválido ou expirou	Troque a chave de acesso novamente e tente mais uma vez
`403`	A credencial não tem permissão ou acesso à organização	Verifique os escopos da chave e o contexto da organização
`404`	O recurso não existe na organização autorizada	Verifique o ID do recurso e a organização
`408`	A solicitação excedeu o tempo limite	Tente novamente com backoff exponencial limitado
`429`	Limite de taxa atingido	Aguarde pelo menos o tempo indicado em `Retry-After`, quando presente
`5xx`	Falha temporária do serviço	Repita leituras seguras com backoff exponencial limitado

O contrato selecionado não publica atualmente um limite de taxa numérico universal nem garante um cabeçalho de resposta com o ID da solicitação para todas as operações. Ao solicitar suporte, registre o horário em UTC, o método, o caminho, o status e o corpo da resposta com dados sensíveis removidos. Não repita automaticamente operações de criação, rotação, revogação ou exclusão, a menos que a operação documente explicitamente a idempotência. Verifique o estado atual do recurso após uma falha de rede ambígua.

Compatibilidade e descontinuação

A V1 evolui de forma aditiva por padrão. Os clientes devem ignorar campos de resposta desconhecidos. Uma alteração incompatível exige um caminho de migração documentado; as operações descontinuadas permanecem na referência com o motivo, a substituição, quando disponível, e a data de encerramento durante o período de migração. Fixe o SDK em uma versão principal compatível e consulte as notas de versão antes de atualizar. Considere a Public API Reference gerada — e não os clientes de aplicativos próprios — como a fonte de referência do esquema.

API Pública, MCP e aplicativo web

Superfície	Uso	Modelo de compatibilidade
API Pública	Sistemas de clientes, parceiros e automação externa	Recursos estáveis e versionados
MCP	Interações com ferramentas de IA baseadas em permissões	Contratos de ferramentas e saídas estruturadas compactas
Aplicativo web	Fluxos de trabalho humanos no produto Living Security	Contratos próprios do aplicativo, que podem evoluir com a interface

Consulte Integração MCP para conectar uma ferramenta de IA à Living Security.

Obtenha ajuda

Entre em contato com o Suporte da Living Security e informe:

Organização e região
Nome e versão do SDK, se utilizado
Carimbo de data e hora em UTC, método e caminho
Status HTTP e corpo do erro com dados sensíveis removidos

Nunca inclua segredos de chaves de acesso, tokens de portador ou dados privados de clientes.

API pública

Referência da API pública

Antes de começar

Hosts regionais

Recursos legados

Autenticação

SDK TypeScript

Solicitação REST direta

Ciclo de vida da chave de acesso

Paginação

Erros

Compatibilidade e descontinuação

API Pública, MCP e aplicativo web

Obtenha ajuda

Conteúdo relacionado

Chaves de acesso da API

Integração MCP

API pública

Referência da API pública

​Antes de começar

​Hosts regionais

​Recursos legados

​Autenticação

​SDK TypeScript

​Solicitação REST direta

​Ciclo de vida da chave de acesso

​Paginação

​Erros

​Compatibilidade e descontinuação

​API Pública, MCP e aplicativo web

​Obtenha ajuda

​Conteúdo relacionado

Chaves de acesso da API

Integração MCP

Antes de começar

Hosts regionais

Recursos legados

Autenticação

SDK TypeScript

Solicitação REST direta

Ciclo de vida da chave de acesso

Paginação

Erros

Compatibilidade e descontinuação

API Pública, MCP e aplicativo web

Obtenha ajuda

Conteúdo relacionado