> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Pública Legada

> Mantenha as integrações /api/v1 existentes que trocam uma chave de acesso da API por um token de portador (bearer).

Este guia aborda as integrações `/api/v1` existentes que trocam uma chave de acesso da API por um token de portador (bearer). Suas credenciais e o formato das requisições diferem da API Pública `/v1`.

Para uma nova integração, comece com o [início rápido da API](/pt-BR/developers/v1/quickstart) e a seção [Autenticação](/pt-BR/developers/v1/authentication). 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 (issuer) da API, fornecido pela Living Security junto com suas credenciais da API Pública
* A URL base regional da organização que você está integrando
* Um ambiente de execução no 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.

<Note>
  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 suas credenciais da API Pública, solicite-o ao [Suporte da Living Security](mailto:support@livingsecurity.com). O ID do emissor não é o ID da chave de acesso nem o ID da organização.
</Note>

## Hosts regionais

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

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

Use a região atribuída à organização no 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 o vínculo 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, requisiçõ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:

1. Troque o segredo da chave de acesso e o ID do emissor da API por um token de portador (bearer) de curta duração e um ID de organização.
2. Envie o token de portador e o ID da organização em cada requisição à API.

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

```http theme={null}
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:

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

Em seguida, troque a chave e configure o SDK:

```typescript theme={null}
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 servidor.

### Requisição REST direta

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

```bash theme={null}
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. Troque a chave de acesso novamente 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 a automação proprietária.
* Escolha os escopos com 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 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 a navegação sequencial.

* `limit` tem o 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 o 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 requisições paginadas de forma independente para depois ordenar você mesmo os resultados parciais.

## Erros

Os erros JSON documentados usam este formato geral:

```json theme={null}
{
  "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 requisiçã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 requisiçã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 | Tente novamente 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 ID da requisição para todas as operações. Registre o horário em UTC, o método, o caminho, o status e o corpo da resposta sanitizado ao solicitar suporte.

Não tente novamente de forma automática 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 substituta quando disponível e a data de desativação durante o período de migração.

Fixe o SDK em uma versão principal compatível e revise as notas de versão antes de atualizar. Trate 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 o 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 de ferramentas de IA com base 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 UI |

Consulte [Integração com MCP](/pt-BR/integrations/mcp) para conectar uma ferramenta de IA ao Living Security.

## Obter ajuda

Entre em contato com o [Suporte da Living Security](mailto:support@livingsecurity.com) 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 de erro sanitizado

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

## Relacionados

<CardGroup cols={2}>
  <Card title="Chaves de acesso da API" icon="key" href="/pt-BR/integrations/api-keys">
    Crie, rotacione e revogue credenciais da API.
  </Card>

  <Card title="Integração com MCP" icon="robot" href="/pt-BR/integrations/mcp">
    Conecte ferramentas de IA compatíveis por meio do Model Context Protocol.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.