> ## 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

> API 액세스 키를 베어러 토큰으로 교환하는 기존 /api/v1 연동을 유지 관리합니다.

이 가이드는 API 액세스 키를 베어러 토큰으로 교환하는 기존 `/api/v1` 연동을 다룹니다. 이러한 연동의 자격 증명과 요청 형식은 `/v1` Public API와 다릅니다.

새로운 연동을 구축하는 경우 [API 빠른 시작](/ko/developers/v1/quickstart)과 [인증](/ko/developers/v1/authentication)부터 확인하십시오. 새로운 `/v1` API는 서비스 계정 API 키 또는 OAuth 액세스 토큰을 사용합니다.

## 시작하기 전에

다음이 필요합니다.

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

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

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

## 리전별 호스트

레거시 계약은 다음과 같은 리전별 `/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 접근은 두 단계로 이루어집니다.

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

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

```http theme={null}
Authorization: Bearer <access-token>
x-organization-id: <organization-id>
```

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

### TypeScript SDK

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

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

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

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

### 직접 REST 요청

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

```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"
```

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

## 액세스 키 수명 주기

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

## 페이지 매김

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

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

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

## 오류

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

```json theme={null}
{
  "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 연동](/ko/integrations/mcp)을 참조하십시오.

## 도움 받기

다음 정보를 포함하여 [Living Security 지원팀](mailto:support@livingsecurity.com)에 문의하십시오.

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

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

## 관련 문서

<CardGroup cols={2}>
  <Card title="API 액세스 키" icon="key" href="/ko/integrations/api-keys">
    API 자격 증명을 생성, 교체 및 해지합니다.
  </Card>

  <Card title="MCP 연동" icon="robot" href="/ko/integrations/mcp">
    Model Context Protocol을 통해 지원되는 AI 도구를 연결합니다.
  </Card>
</CardGroup>


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