API 빠른 시작

Developer Hub에서 서비스 계정과 API 키를 생성한 후 첫 번째 요청을 보내십시오. 이 빠른 시작 가이드에서는 API 키 인증을 사용하며, OAuth 클라이언트는 필요하지 않습니다. 연동에 수명이 짧은 OAuth 액세스 토큰이 필요한 경우 인증을 참조하십시오.

사전 요구 사항

Living Security 대시보드에 대한 관리자 액세스 권한.
설정 → 연동 및 개발자 → Developer Hub에 Developer Hub가 표시되어 있어야 합니다.

자격 증명 생성

서비스 계정 생성

Developer Hub에서 Service accounts 탭을 열고 계정을 생성합니다. 용도를 알 수 있는 이름(예: reporting-pipeline)을 지정하고, 해당 계정의 키가 사용할 수 있는 권한을 부여합니다. 이 가이드에서는 organization:read만 있으면 충분합니다.서비스 계정의 권한은 그 아래에서 생성되는 모든 키의 상한입니다. 키는 서비스 계정이 허용하는 범위를 넘어서는 작업을 수행할 수 없습니다.

API 키 생성

서비스 계정의 상세 페이지를 열고 키를 생성합니다. 해당 키에 필요한 권한(계정 권한의 하위 집합)과 만료 기간(30일, 90일, 365일 또는 사용자 지정 기간)을 선택합니다. 만료 기간은 필수입니다.키의 시크릿은 lsk_live_로 시작하며 한 번만 표시됩니다. 즉시 시크릿 관리자에 복사해 두십시오. 나중에는 다시 확인할 수 없습니다.

API 키 시크릿을 버전 관리 시스템에 커밋하거나 클라이언트 측 코드에 포함하지 마십시오. 시크릿을 보유한 사람은 누구나 해당 키의 권한으로 작업을 수행할 수 있습니다.

리전 선택

조직의 데이터 상주 지역에 맞는 리전별 /v1 호스트를 호출하십시오. 키는 해당 호스트에서만 인증됩니다.

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

어떤 호스트를 사용해야 할지 확실하지 않은 경우 리전을 참조하십시오. 유효한 키를 다른 리전으로 보내면 unauthorized(으)로 실패합니다. 아래 샘플의 리전 드롭다운을 사용하여 호스트를 전환할 수 있습니다.

첫 번째 요청 보내기

시크릿 관리자에서 LIVING_SECURITY_API_KEY을(를) 요청을 보내는 프로세스의 환경에 불러옵니다. 아래 예제는 소스 코드에 시크릿을 포함하지 않고 이를 읽어 옵니다. Python의 경우 먼저 requests을(를) 설치하십시오.HTTP Basic 인증의 비밀번호 또는 사용자 이름 필드에 시크릿을 넣어 API를 호출합니다. 어느 쪽이든 동작하므로, 두 필드를 모두 채워야 하는 클라이언트(예: Power BI의 Web 커넥터)에서는 다른 필드에 apikey 같은 자리 표시자를 입력하면 됩니다.

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

요청이 성공하면 조직 정보가 반환됩니다.

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

이 응답을 받았다면 자격 증명이 정상적으로 작동하는 것입니다. 해당 요청은 잠시 후 Developer Hub의 Request logs 탭에도 표시됩니다.

동일한 시크릿(Authorization: Bearer lsk_live_...)을 사용하는 Bearer 인증도 지원됩니다. Basic 인증은 Power BI의 Web 커넥터처럼 사용자 이름/비밀번호 방식만 지원하는 도구가 연결할 수 있도록 제공됩니다.

인증 작동 방식

자격 증명이 조직을 결정합니다. /v1 요청에는 테넌트 선택기가 없습니다. 즉, 조직 경로 세그먼트도 조직 헤더도 사용하지 않습니다. x-organization-id 헤더를 보내면 invalid_request(으)로 거부됩니다. 호스트는 여전히 해당 조직의 리전과 일치해야 합니다. 리전을 참조하십시오.
권한은 작업별로 확인됩니다. 각 /v1 작업에는 지정된 권한이 필요합니다(예: GET /v1/organization에는 organization:read 필요). 해당 권한이 없는 키는 코드 insufficient_permission과(와) 함께 403을(를) 받습니다.
키는 만료되며 중단 없이 교체할 수 있습니다. 중첩 기간을 두고 교체하는 방법은 API 키를 참조하십시오.

오류 응답 읽기

모든 /v1 오류는 고정된 머신 코드를 포함한 application/problem+json(RFC 9457)입니다. 예를 들어 자격 증명이 없거나 알 수 없는 자격 증명으로 요청하면 다음과 같이 반환됩니다.

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

code을(를) 기준으로 분기하고, detail은(는) 기준으로 삼지 마십시오. 해결 방법은 doc_url을(를) 따르고, 지원팀에 문의할 때는 request_id을(를) 함께 제공하십시오. 이 값은 Request-Id 응답 헤더 및 Developer Hub 요청 로그와 일치합니다. 전체 코드 목록은 오류 참조에서 확인할 수 있습니다.

계약 버전

모든 응답은 해당 응답을 처리한 계약 버전을 Living-Security-Version 헤더에 포함하며, 상관 관계 확인을 위한 Request-Id 헤더도 함께 제공합니다. 게시된 계약 버전을 날짜로 지정하여 요청을 고정할 수 있습니다.

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

버전은 다음 순서로 결정됩니다. 요청 헤더가 있으면 해당 값, 없으면 서비스 계정에 고정된 기본값, 그마저 없으면 게시된 최신 버전입니다. 게시되지 않았거나 종료일이 지난 버전을 요청하면 코드 unsupported_version과(와) 함께 400을(를) 반환합니다. 게시된 버전과 변경 사항은 API 변경 로그에 나와 있습니다.

첫 번째 요청 문제 해결

결과	다음 조치
`401 unauthorized`	시크릿, 만료 기간, 조직의 리전을 확인하십시오. 유효한 자격 증명으로 다른 호스트를 시도하지 마십시오.
`403 insufficient_permission`	서비스 계정과 해당 키 모두에 `organization:read`을(를) 부여하십시오.
`400 unsupported_version`	변경 로그에서 게시된 버전을 선택하십시오.
`429 rate_limited`	`Retry-After`까지 기다린 후 제한된 재시도 예제를 따르십시오.
네트워크 시간 초과	연결 상태를 확인하고 애플리케이션의 재시도 허용 범위 내에서 이 읽기 요청을 다시 시도하십시오.

그 밖의 오류는 응답의 doc_url을(를) 따르십시오. 지원팀에 전달할 수 있도록 Request-Id을(를) 보관하되, 티켓에 Authorization 헤더나 API 키를 포함하지 마십시오.

다음 단계

리전

조직에 맞는 US 또는 EU /v1 호스트를 선택합니다.

페이지 매김

page_token 및 목록 엔벨로프를 사용하여 목록을 순회합니다.

요청 제한

요청 허용량을 이해하고 429 응답을 처리합니다.

오류 참조

모든 오류 코드, HTTP 상태 및 해결 방법을 확인합니다.

Developer Hub

서비스 계정, API 키 및 요청 로그를 관리합니다.

개발자 허브

공개 API v1

API v1 참조

사전 요구 사항

자격 증명 생성

인증 작동 방식

오류 응답 읽기

계약 버전

첫 번째 요청 문제 해결

다음 단계

리전

페이지 매김

요청 제한

오류 참조

Developer Hub

개발자 허브

공개 API v1

API v1 참조

​사전 요구 사항

​자격 증명 생성

​인증 작동 방식

​오류 응답 읽기

​계약 버전

​첫 번째 요청 문제 해결

​다음 단계

리전

페이지 매김

요청 제한

오류 참조

Developer Hub

사전 요구 사항

자격 증명 생성

인증 작동 방식

오류 응답 읽기

계약 버전

첫 번째 요청 문제 해결

다음 단계