> ## 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 빠른 시작 > Developer Hub에서 서비스 계정과 API 키를 생성하고, Basic 인증으로 인증한 후 Living Security Public API에 첫 번째 요청을 보내십시오. Developer Hub에서 서비스 계정과 API 키를 생성한 후 첫 번째 요청을 보내십시오. 이 빠른 시작 가이드에서는 API 키 인증을 사용하며, OAuth 클라이언트는 필요하지 않습니다. 연동에 수명이 짧은 OAuth 액세스 토큰이 필요한 경우 [인증](/ko/developers/v1/authentication)을 참조하십시오. ## 사전 요구 사항 * Living Security 대시보드에 대한 관리자 액세스 권한. * **설정 → 연동 및 개발자 → Developer Hub**에 Developer Hub가 표시되어 있어야 합니다. ## 자격 증명 생성 Developer Hub에서 **Service accounts** 탭을 열고 계정을 생성합니다. 용도를 알 수 있는 이름(예: `reporting-pipeline`)을 지정하고, 해당 계정의 키가 사용할 수 있는 권한을 부여합니다. 이 가이드에서는 `organization:read`만 있으면 충분합니다. 서비스 계정의 권한은 그 아래에서 생성되는 모든 키의 상한입니다. 키는 서비스 계정이 허용하는 범위를 넘어서는 작업을 수행할 수 없습니다. 서비스 계정의 상세 페이지를 열고 키를 생성합니다. 해당 키에 필요한 권한(계정 권한의 하위 집합)과 만료 기간(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` | 어떤 호스트를 사용해야 할지 확실하지 않은 경우 [리전](/ko/developers/v1/regions)을 참조하십시오. 유효한 키를 다른 리전으로 보내면 `unauthorized`(으)로 실패합니다. 아래 샘플의 리전 드롭다운을 사용하여 호스트를 전환할 수 있습니다. 시크릿 관리자에서 `LIVING_SECURITY_API_KEY`을(를) 요청을 보내는 프로세스의 환경에 불러옵니다. 아래 예제는 소스 코드에 시크릿을 포함하지 않고 이를 읽어 옵니다. Python의 경우 먼저 `requests`을(를) 설치하십시오. HTTP Basic 인증의 비밀번호 또는 사용자 이름 필드에 시크릿을 넣어 API를 호출합니다. 어느 쪽이든 동작하므로, 두 필드를 모두 채워야 하는 클라이언트(예: Power BI의 Web 커넥터)에서는 다른 필드에 `apikey` 같은 자리 표시자를 입력하면 됩니다. ```bash cURL theme={null} 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" ``` ```bash cURL (key as username) theme={null} 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" ``` ```python Python theme={null} 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()) ``` 요청이 성공하면 조직 정보가 반환됩니다. ```json Response theme={null} { "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`(으)로 거부됩니다. 호스트는 여전히 해당 조직의 리전과 일치해야 합니다. [리전](/ko/developers/v1/regions)을 참조하십시오. * **권한은 작업별로 확인됩니다.** 각 `/v1` 작업에는 지정된 권한이 필요합니다(예: `GET /v1/organization`에는 `organization:read` 필요). 해당 권한이 없는 키는 코드 `insufficient_permission`과(와) 함께 `403`을(를) 받습니다. * **키는 만료되며 중단 없이 교체할 수 있습니다.** 중첩 기간을 두고 교체하는 방법은 [API 키](/ko/developers/developer-hub/api-keys)를 참조하십시오. ## 오류 응답 읽기 모든 `/v1` 오류는 고정된 머신 코드를 포함한 `application/problem+json`([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457))입니다. 예를 들어 자격 증명이 없거나 알 수 없는 자격 증명으로 요청하면 다음과 같이 반환됩니다. ```json 401 Unauthorized theme={null} { "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 요청 로그와 일치합니다. 전체 코드 목록은 [오류 참조](/ko/developers/v1/errors/overview)에서 확인할 수 있습니다. ## 계약 버전 모든 응답은 해당 응답을 처리한 계약 버전을 `Living-Security-Version` 헤더에 포함하며, 상관 관계 확인을 위한 `Request-Id` 헤더도 함께 제공합니다. 게시된 계약 버전을 날짜로 지정하여 요청을 고정할 수 있습니다. ```bash cURL theme={null} 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 변경 로그](/ko/developers/v1/changelog)에 나와 있습니다. ## 첫 번째 요청 문제 해결 | 결과 | 다음 조치 | | - | - | | `401 unauthorized` | 시크릿, 만료 기간, 조직의 리전을 확인하십시오. 유효한 자격 증명으로 다른 호스트를 시도하지 마십시오. | | `403 insufficient_permission` | 서비스 계정과 해당 키 모두에 `organization:read`을(를) 부여하십시오. | | `400 unsupported_version` | [변경 로그](/ko/developers/v1/changelog)에서 게시된 버전을 선택하십시오. | | `429 rate_limited` | `Retry-After`까지 기다린 후 [제한된 재시도 예제](/ko/developers/v1/rate-limits)를 따르십시오. | | 네트워크 시간 초과 | 연결 상태를 확인하고 애플리케이션의 재시도 허용 범위 내에서 이 읽기 요청을 다시 시도하십시오. | 그 밖의 오류는 응답의 `doc_url`을(를) 따르십시오. 지원팀에 전달할 수 있도록 `Request-Id`을(를) 보관하되, 티켓에 Authorization 헤더나 API 키를 포함하지 마십시오. ## 다음 단계 조직에 맞는 US 또는 EU `/v1` 호스트를 선택합니다. `page_token` 및 목록 엔벨로프를 사용하여 목록을 순회합니다. 요청 허용량을 이해하고 `429` 응답을 처리합니다. 모든 오류 코드, HTTP 상태 및 해결 방법을 확인합니다. 서비스 계정, API 키 및 요청 로그를 관리합니다. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.