인증 방식

모든 요청은 Authorization 헤더에 API 키를 담아 보냅니다.

Authorization: Bearer lp_live_XXXXXXXX…    (워크스페이스 키)
Authorization: Bearer lpp_live_XXXXXXXX…   (파트너 키)

키는 대시보드에서 만들며, 생성 시 한 번만 표시되고 SHA-256 해시로 저장됩니다. 지원팀을 포함해 그 누구도 잃어버린 키를 복구할 수 없습니다. 키를 분실했다면 그 키를 폐기하고 새로 만드는 수밖에 없습니다.

키 종류

• 워크스페이스 키(lp_live_…)는 워크스페이스 한 곳 안에서 동작하며 링크, 분석, 도메인, 감사 로그, 워크스페이스 웹훅을 다룹니다. 워크스페이스 관리자가 설정 → API 키에서 만듭니다.
• 파트너 키(lpp_live_…)는 파트너 계정을 대상으로 동작하며 고객, 요금제, 도메인, 결제, 정산, 파트너 웹훅을 다룹니다. 파트너 관리자가 만듭니다.

워크스페이스 키로 /partner/*를 호출하면(그 반대도 마찬가지) 403 forbidden이 반환됩니다. 두 엔드포인트 계열은 엄격하게 분리되어 있습니다.

스코프

스코프는 키를 만들 때 키 단위로 부여합니다. 요청은 해당 엔드포인트가 요구하는 모든 스코프를 갖춰야 하며, 빠진 스코프가 있으면 그 이름을 알려 주는 403 insufficient_scope가 반환됩니다.

| 스코프 | 허용 범위 | |---|---| | links:read / links:write | 링크 조회 / 생성, 수정, 보관, 삭제 | | analytics:read | 요약, 시계열, 세부 분석, 인기 링크, CSV 내보내기, 그리고 파트너 전체 클릭 수 개요 | | domains:read / domains:write | 도메인 조회 / 연결 및 연결 해제 | | qr:read | 링크의 QR 코드 생성 | | workspace:read | 워크스페이스 프로필, 제한, 감사 로그 | | webhooks:read / webhooks:write | 웹훅 엔드포인트 조회 / 관리 | | partner:read | 파트너 프로필, 요금제, 사용량 | | clients:read / clients:write | 고객 조회 / 생성, 변경, 정지 | | plans:read / plans:write | 파트너 요금제 조회 / 관리 | | payments:read | 결제 미러와 정산 |

이것이 전체 목록입니다. 스코프는 모두 열다섯 개이며, 키에는 이 목록에 있는 이름만 담을 수 있습니다. QR 코드는 API에서 읽기 전용입니다. QR 코드를 생성하려면 qr:read가 필요하고, QR을 변경하는 엔드포인트 자체가 없으므로 QR 쓰기 스코프도 없습니다.

한 가지 조합이 자주 혼동을 부릅니다. GET /partner/analytics/overview에는 파트너 키의 partner:read가 아니라 analytics:read가 필요합니다. 모든 분석 엔드포인트는 키 종류와 상관없이 같은 스코프를 사용합니다.

연동마다 별도의 키를 두고 꼭 필요한 최소 스코프만 부여하십시오. 대시보드 위젯용 키는 links:read + analytics:read로 충분하지만, 프로비저닝 스크립트에는 clients:write가 필요합니다.

요금제에 따른 제한

API 접근 권한은 요금제 기능(api_access)입니다.

• 워크스페이스 키는 워크스페이스 요금제와 파트너의 플랫폼 요금제 양쪽 모두에 API 접근이 포함되어 있어야 합니다.
• 파트너 키는 파트너의 플랫폼 요금제에 API 접근이 포함되어 있어야 합니다.

API 접근이 없는 요금제는 403 plan_restricted를 반환합니다. 아직 요금제가 없는 체험판 워크스페이스는 제한받지 않습니다.

교체와 폐기

키를 폐기하면 즉시 적용되어 다음 요청부터 401 unauthorized가 반환됩니다. 중단 없이 키를 교체하려면 새 키를 먼저 만들고, 연동을 새 키로 전환한 다음, 이전 키를 폐기하십시오. 키마다 last_used_at이 기록되므로 폐기하기 전에 쓰이지 않는 오래된 키를 쉽게 가려낼 수 있습니다.

키에는 만료일을 선택적으로 지정할 수도 있습니다. 만료된 키는 폐기된 키와 완전히 똑같이 동작합니다.

권장 사항

• 키는 비밀 정보입니다. 시크릿 관리 도구에 보관하고 클라이언트 측 코드, 저장소, 로그에는 절대 두지 마십시오.
• 연동당 키는 하나씩 두십시오. 키 하나를 폐기해도 나머지 연동은 멈추지 않고, 감사 로그가 모든 변경을 그 변경을 수행한 키에 귀속시켜 기록합니다.