> ## 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.
# Public API
> Use the Living Security public API for stable customer and partner integrations.
The Living Security public API is the stable REST contract for customer
systems, partner integrations, and external automation.
The public API is separate from the in-product web application, private
application endpoints, and agent-specific MCP tools. A feature
appearing in the product does not automatically mean it is available in the
public API.
## Integration surfaces
| Surface | Use for | Contract |
| --------------- | ------------------------------------------------------ | --------------------------------------------------------------------------- |
| Public API | Customer systems, partner integrations, and automation | Stable, versioned resources documented here |
| MCP | Agent and AI-tool integrations | Permissioned tool actions with compact responses |
| Web application | Human workflows in the Living Security platform | Product UI and page-shaped app contracts, not a public integration contract |
Do not build customer integrations against browser network calls, dashboard
URLs, or undocumented platform endpoints. Those routes are optimized for the
web application and may change without public API deprecation notice.
## What is not public API
The following are not public API contracts:
* browser network calls from the web application
* undocumented platform endpoints or private application routes
* locally generated API explorers or broad development references
* generated clients used by Living Security web applications
* MCP or Livvy tool responses
* database tables, private DTOs, or page-shaped response models
Public API availability starts with a documented resource in this Developers
section and the generated Public API Reference. If a product screen exposes a
value that is not documented here, treat it as product UI only and ask your
Living Security contact before automating against it.
## Base URL and versioning
Use the API base URL provided by Living Security for your environment. Public
REST endpoints are versioned under `/api/v1`.
| Region | Base URL |
| ------ | ------------------------------------------------ |
| US | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| EU | `https://api.eu-west-1.livingsecurity.ai/api/v1` |
The v1 public API evolves additively by default. New response fields may appear
without a version change, so clients should ignore unknown fields. Removing or
renaming endpoints or fields, changing field types, narrowing accepted values,
or changing authentication, authorization, tenant, or pagination semantics
requires a documented migration path.
Deprecated operations remain in the API reference during their migration
window. A deprecated operation includes a sunset date, a deprecation reason, and
a migration guide. When a direct replacement exists, the reference also names
the replacement operation.
## Current v1 resources
The current public API catalog is intentionally small and resource-oriented.
Endpoints are promoted when they have a stable customer use case, documented
authorization behavior, and a supportable compatibility path.
| Resource | Capability |
| ---------------------- | -------------------------------------------------------- |
| People and memberships | Search people and retrieve a person's membership record. |
| API access keys | Create, list, rotate, and revoke API access keys. |
See the Public API Reference section in the Developers tab for the current
endpoint list generated from the curated public API contract.
## Promotion standard
An endpoint becomes public API only after it has:
* a concrete customer-facing entity or resource model
* stable request and response DTOs that do not expose database or page models
* documented authentication, tenant, error, pagination, filter, and sort
behavior where applicable
* permission and tenant-isolation coverage
* compatibility review, SDK generation, and this documentation updated
Internal page-shaped endpoints can move faster because they are owned by the
Living Security web apps. That speed is intentional and separate from public
API compatibility guarantees.
## Authentication
Public API integrations use Living Security API access keys created in the
Living Security platform. Create and manage keys in **Settings -> Access Keys**.
Exchange the secret access key value for a bearer access token, then call the
public API with both headers:
* `Authorization: Bearer `
* `x-organization-id: `
The official TypeScript SDK can perform the access-key exchange and inject the
required headers for Node.js scripts, serverless functions, CLI tools, and agent
integrations. Use the secret access key value and API issuer ID provided with
your public API credentials.
```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,
});
```
If you call the REST API directly, send the bearer token and organization
header on each request.
```bash theme={null}
curl "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
-H "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
-H "x-organization-id: $LIVING_SECURITY_ORG_ID"
```
Use the least-privileged key scope that supports your integration. Store API
access keys and bearer access tokens in your secret manager and never place
them in browser code, mobile apps, source control, or shared logs.
## Request patterns
Use documented resource identifiers, filters, sorting options, and pagination
parameters only. Undocumented fields, web application URLs, and page-specific
payloads are not public API contract.
When a list endpoint is paginated, treat page boundaries and total counts as
owned by that endpoint. Do not combine separately paginated requests and then
sort the partial rows client-side.
## Errors, rate limits, and retries
Errors use standard HTTP status codes and documented response bodies in the API
reference. Treat `401` as an expired or invalid bearer access token, `403` as
missing permission or tenant access, `404` as a missing resource, and `400` as
invalid input.
Clients should handle transient `408`, `429`, and `5xx` responses with bounded
exponential backoff. If a response includes `Retry-After`, wait at least that
long before retrying.
Do not assume a write endpoint is idempotent unless the endpoint reference says
so. If a network failure happens after a create, rotate, or revoke request,
check resource state before retrying.
## MCP
MCP is available for agentic workflows that need tool-style interactions rather
than REST resources. MCP tools share the same tenant and permission expectations
as the rest of the platform, but they are not the public REST API and they are
not web application endpoints.
MCP tools are designed around permissioned actions and compact structured
outputs for AI clients. They may use the same backend use cases as public REST
resources, but tool responses should not be treated as REST DTOs and REST
resources should not be created by copying tool output.
See [MCP Integration](/integrations/mcp) for setup.
## Related
Create and manage credentials for API access.
Connect AI tools through the Model Context Protocol.