레거시 Public API

이 가이드는 API 액세스 키를 베어러 토큰으로 교환하는 기존 /api/v1 연동을 다룹니다. 이러한 연동의 자격 증명과 요청 형식은 /v1 Public API와 다릅니다. 새로운 연동을 구축하는 경우 API 빠른 시작과 인증부터 확인하십시오. 새로운 /v1 API는 서비스 계정 API 키 또는 OAuth 액세스 토큰을 사용합니다.

시작하기 전에

다음이 필요합니다.

API 액세스 키 관리를 허용하는 Living Security 접근 권한
설정 → Access Keys에서 생성한 API 액세스 키
자격 증명을 생성할 때 한 번만 표시되는 액세스 키 시크릿
Living Security에서 Public API 자격 증명과 함께 제공한 API 발급자 ID
연동하려는 조직의 리전별 기본 URL
서버 측 런타임 및 시크릿 관리자

액세스 키 시크릿을 브라우저 코드, 모바일 앱, 소스 제어, 클라이언트 측 환경 변수, 티켓 또는 공유 로그에 포함해서는 안 됩니다.

Access Keys 대화 상자에는 한 번만 표시되는 시크릿이 나타나지만 API 발급자 ID는 표시되지 않습니다. Living Security에서 Public API 자격 증명과 함께 발급자 ID를 제공하지 않았다면 Living Security 지원팀에 요청하십시오. 발급자 ID는 액세스 키 ID 또는 조직 ID와 다릅니다.

리전별 호스트

레거시 계약은 다음과 같은 리전별 /api/v1 프로덕션 호스트를 사용합니다.

리전	기본 URL
US	`https://api.us-east-1.livingsecurity.ai/api/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Living Security 조직에 할당된 리전을 사용하십시오. 권한 부여 오류 또는 가용성 오류를 우회하기 위해 리전을 변경하지 마십시오.

레거시 리소스

리소스	지원되는 작업
사람들	조직 구성원 검색 및 특정 구성원의 멤버십 조회
API 액세스 키	API 액세스 키 생성, 조회, 교체 및 해지

전체 작업, 매개변수, 요청, 응답 및 스키마 목록은 Developers → Public API Reference를 참조하십시오. 해당 위치에 없는 작업은 현재 Public API에 포함되지 않습니다.

인증

Public API 접근은 두 단계로 이루어집니다.

시크릿 액세스 키와 API 발급자 ID를 단기 베어러 토큰 및 조직 ID로 교환합니다.
각 API 요청과 함께 베어러 토큰과 조직 ID를 전송합니다.

필수 요청 헤더는 다음과 같습니다.

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

조직 헤더에는 액세스 키 교환으로 반환된 조직을 사용해야 합니다. 키가 임의의 조직 ID에 대한 접근을 승인하지는 않습니다.

TypeScript SDK

현재 메이저 버전을 설치하십시오.

npm install @livingsecurity/sdk@^1

그런 다음 키를 교환하고 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,
});

EU 조직에는 EU 기본 URL을 사용하십시오. SDK 교환은 서버 측 Node.js 런타임에서 사용하도록 설계되었습니다.

직접 REST 요청

SDK 외부에서 교환을 수행하는 경우 모든 요청에 해당 베어러 토큰과 조직 ID를 전송하십시오.

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"

베어러 토큰은 수명이 짧습니다. 베어러 토큰을 영구 자격 증명으로 저장하지 말고, 새 토큰이 필요할 때 액세스 키를 다시 교환하십시오.

액세스 키 수명 주기

키 이름은 해당 키를 소유한 연동 또는 자동화의 이름으로 지정하십시오.
액세스 키 양식에서 제공하는 범위 중 최소 권한 범위를 선택하십시오.
한 번만 표시되는 시크릿은 즉시 저장하십시오. 생성 또는 교체 후에는 다시 조회할 수 없습니다.
설정 → Access Keys에서 키를 교체하고, 이전 자격 증명을 해지하기 전에 교체한 키를 배포하십시오.
더 이상 사용하지 않거나 시크릿이 노출되었을 수 있는 키는 해지하십시오.
조직에서 사용할 수 있는 경우 사람이 아닌 연동에는 서비스 계정 키를 사용하십시오.

페이지 매김

사람들 검색은 limit, cursor, offset 및 includeTotal 매개변수를 지원합니다. 순차적으로 탐색할 때는 이전 응답에서 반환된 커서를 사용하는 것이 좋습니다.

limit의 기본값은 50이며 1–100을 허용합니다.
cursor는 이전 응답에 이어서 조회합니다.
offset는 지정한 수만큼 레코드를 건너뛰며 기본값은 0입니다.
includeTotal=true는 필터링된 정확한 개수를 요청합니다. 개수가 필요하지 않으면 생략하십시오.

엔드포인트에서 반환된 pagination 객체를 읽으십시오. 수신한 행 수로 다음 페이지를 계산하거나, 각각 페이지 매김한 요청을 결합하여 부분 결과를 직접 정렬하지 마십시오.

오류

문서화된 JSON 오류는 다음과 같은 일반적인 형식을 사용합니다.

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

message은 문자열 또는 유효성 검사 메시지 배열일 수 있습니다.

상태	의미	대응
`400`	매개변수 또는 요청 본문이 잘못됨	명시된 유효성 검사 오류를 수정하십시오
`401`	베어러 토큰이 없거나 유효하지 않거나 만료됨	액세스 키를 다시 교환한 후 한 번 재시도하십시오
`403`	자격 증명에 권한 또는 조직 접근 권한이 없음	키 범위와 조직 컨텍스트를 확인하십시오
`404`	승인된 조직에 리소스가 존재하지 않음	리소스 ID와 조직을 확인하십시오
`408`	요청 시간 초과	제한된 지수 백오프로 재시도하십시오
`429`	속도 제한에 도달함	`Retry-After`가 있는 경우 해당 시간 이상 대기하십시오
`5xx`	일시적인 서비스 장애	안전한 읽기 요청은 제한된 지수 백오프로 재시도하십시오

선별된 계약은 현재 모든 작업에 적용되는 단일 숫자 속도 제한을 게시하지 않으며, 모든 작업에 대해 요청 ID 응답 헤더를 보장하지도 않습니다. 지원을 요청할 때는 UTC 시간, 메서드, 경로, 상태 및 민감 정보를 제거한 응답 본문을 함께 제공하십시오. 작업에 멱등성이 명시적으로 문서화되어 있지 않다면 생성, 교체, 해지 또는 삭제 작업을 자동으로 재시도하지 마십시오. 네트워크 장애로 결과가 불분명한 경우 리소스의 현재 상태를 확인하십시오.

호환성 및 지원 중단

V1은 기본적으로 추가 방식으로 발전합니다. 클라이언트는 알 수 없는 응답 필드를 무시해야 합니다. 호환성을 깨는 변경에는 문서화된 마이그레이션 경로가 필요하며, 지원 중단된 작업은 마이그레이션 기간 동안 그 사유, 사용 가능한 경우 대체 작업 및 종료 날짜와 함께 레퍼런스에 유지됩니다. SDK를 호환되는 메이저 버전으로 고정하고, 업그레이드하기 전에 릴리스 노트를 검토하십시오. 스키마의 기준 출처로는 자사 앱 클라이언트가 아닌 생성된 Public API Reference를 사용하십시오.

Public API, MCP 및 웹 애플리케이션

인터페이스	용도	호환성 모델
Public API	고객 시스템, 파트너 및 외부 자동화	안정적이며 버전이 관리되는 리소스
MCP	권한이 부여된 AI 도구 상호작용	도구 계약 및 간결한 구조화 출력
웹 애플리케이션	Living Security 제품 내 사용자 워크플로	UI와 함께 변경될 수 있는, 앱이 관리하는 계약

AI 도구를 Living Security에 연결하려면 MCP 연동을 참조하십시오.

도움 받기

다음 정보를 포함하여 Living Security 지원팀에 문의하십시오.

조직 및 리전
사용한 경우 SDK 이름 및 버전
UTC 타임스탬프, 메서드 및 경로
HTTP 상태 및 민감 정보를 제거한 오류 본문

액세스 키 시크릿, 베어러 토큰 또는 비공개 고객 데이터는 절대 포함하지 마십시오.

API 액세스 키

API 자격 증명을 생성, 교체 및 해지합니다.

MCP 연동

Model Context Protocol을 통해 지원되는 AI 도구를 연결합니다.

공개 API

공개 API 참조

시작하기 전에

리전별 호스트

레거시 리소스

인증

TypeScript SDK

직접 REST 요청

액세스 키 수명 주기

페이지 매김

오류

호환성 및 지원 중단

Public API, MCP 및 웹 애플리케이션

도움 받기

관련 문서

API 액세스 키

MCP 연동

공개 API

공개 API 참조

​시작하기 전에

​리전별 호스트

​레거시 리소스

​인증

​TypeScript SDK

​직접 REST 요청

​액세스 키 수명 주기

​페이지 매김

​오류

​호환성 및 지원 중단

​Public API, MCP 및 웹 애플리케이션

​도움 받기

​관련 문서

API 액세스 키

MCP 연동

시작하기 전에

리전별 호스트

레거시 리소스

인증

TypeScript SDK

직접 REST 요청

액세스 키 수명 주기

페이지 매김

오류

호환성 및 지원 중단

Public API, MCP 및 웹 애플리케이션

도움 받기

관련 문서