비공개 API 키를 생성하거나 복제하는 방법

학습 내용

비공개 API 키를 생성하거나 복제하는 방법과 애플리케이션이 Klaviyo 계정에서 액세스할 수 있는 항목을 제어하는 범위를 선택하는 방법을 알아보세요.

비공개 API 키와 범위는 타사에서 액세스할 수 있는 항목을 제한하여 사용자와 고객의 데이터를 보호하는 데 도움이 돼요.

비공개 API 키 및 범위 정보

API 호출을 사용하면 한 애플리케이션이 다른 애플리케이션에서 정보를 요청하거나 추가하거나 편집할 수 있어요.

비공개 API 키는 Klaviyo 계정을 식별하고, 키에 할당된 범위를 사용해 API 요청을 승인해요. 누구든지 이 키를 가지고 있으면 해당 권한을 사용할 수 있으니, 비밀번호처럼 다뤄 주세요.

비공개 API 키에 스코프를 포함하면 추가적인 인증 계층이 더해져 타사가 액세스할 수 있는 특정 요소가 제한돼요. 범위(scope)는 호텔 키와 비슷해서, 건물 전체가 아니라 특정 구역(예: 객실이나 헬스장)에만 접근할 수 있게 해줘요.

범위 액세스 수준

비공개 API 키를 만들 때 각 API 범위에 대한 액세스 수준을 선택하세요. 이러한 액세스 수준은 타사에서 다음 작업을 할 수 있는지 여부를 결정해요:

• 해당 범위(scope)에 포함된 데이터나 작업에 액세스할 수 없습니다.
• 변경하지 않고 해당 범위에서 제공되는 데이터를 볼 수 있어요(읽기 권한).
• 해당 범위에서 다루는 데이터를 보고, 만들거나 삭제하거나, 그 밖의 변경을 할 수 있어요(읽기/쓰기 권한).

예를 들어, 다른 애플리케이션에서 프로필을 마케팅에 구독하고 Klaviyo 리스트에 추가하려면 프로필 대량 구독을(를) 사용하세요. 이 엔드포인트에는 lists:write, profiles:write, subscriptions:write가 필요해요. 이러한 범위에 대해 읽기/쓰기 액세스를 부여하면 이 요청이 처리되므로, 관련 없는 범위에 대한 액세스를 부여할 필요는 없어요.

개발자 포털에서 Klaviyo API에 대해 알아보고, 각 엔드포인트에서 사용 가능한 범위를 확인할 수 있어요.

시작하기 전에 알아야 할 것

다음 사항에 유의하세요:

• 비공개 API 키를 만든 후에는 다음을 할 수 없어요:
  • 확인 페이지를 나간 후에는 비공개 API 키 전체를 다시 볼 수 없어요.
    • 팁: 비공개 API 키는 안전하게 저장하고, 비밀번호 관리자 등에서 어떤 용도로 사용할지 메모해 두세요.
  • 해당 범위를 추가하거나 편집하세요.
    • 다른 범위가 필요하면 필요한 액세스 권한이 있는 새 비공개 API 키를 생성해 주세요. 기존 키를 사용하는 모든 연동을 업데이트하고, 삭제하기 전에 정상적으로 작동하는지 확인해 주세요.
• 생성 페이지는 사용자 지정 키가 선택된 상태로 시작돼요. 키를 생성하기 전에 최소 1개의 API 범위에 대한 액세스를 선택해 주세요.

어떤 API 엔드포인트, 범위 또는 권한이 필요한지 확신이 서지 않으면 개발자에게 문의하거나 도움을 받기 위해 Klaviyo 파트너에게 문의해 주세요.

비공개 API 키 생성

1. 왼쪽 하단에서 조직 이름을 클릭합니다.
2. 설정으로 이동합니다.
3. Click API 키.
   

4. 비공개 API 키 생성을 클릭하세요.
5. API 키 이름을 지정하세요.
6. 액세스 수준 선택에서 연동에 필요한 액세스를 선택하세요:
   • 읽기 전용 키: 사용 가능한 모든 API 범위에 대한 읽기 액세스를 부여해요.
   • 전체 액세스 키: 사용 가능한 모든 API 범위에 대한 읽기/쓰기 액세스를 부여해요.
   • 사용자 지정 키: API 범위 아래의 각 행에서 액세스 없음, 읽기 액세스 또는 읽기/쓰기 액세스를 선택할 수 있어요. 최소 1개 이상의 범위에 대한 액세스 권한을 선택하세요.

7. 생성을 선택합니다.
8. 확인 페이지에서 복사 아이콘(키 복사) 또는 다운로드 아이콘(다운로드(.txt))을 사용해 키를 안전한 곳에 저장해 주세요. 이 페이지를 벗어나면 전체 키를 다시 확인할 수 없어요.
9. 닫기를 선택하여 API 키로 돌아갑니다.

이제 비공개 API 키를 공유하면 서드파티는 범위에서 정의한 정보에만 액세스할 수 있어요.

비공개 API 키 복제

복제하면 원래 키의 스코프를 사용해 새 비공개 API 키가 생성돼요. 이름이 변경된 스코프는 현재 이름을 사용하고, 대체 항목이 없는 사용 중단된 스코프는 제외돼요.

참고:

• 복제하면 원래의 비공개 API 키와 동일한 키가 생성되지 않습니다.
• 복제된 API 키는 원본과 동일한 이름을 사용해요. API 키 설정에서 이름을 변경할 수 없어요.

비공개 API 키를 복제하려면 다음을 수행하세요:

1. 설정 > API 키로 이동하세요.
2. 복제하려는 키 옆의 점 3개 메뉴를 클릭합니다.
3. 복제를 선택한 다음, 확인 대화상자에서 복제를 다시 선택해 주세요.

4. 복사 아이콘(키 복사) 또는 다운로드 아이콘(다운로드(.txt))을 사용해 새 키를 안전한 곳에 저장한 다음 닫기를 선택해 주세요. 이 페이지를 닫으면 전체 키를 다시 볼 수 없어요.
5. 원래 키를 교체하는 경우, 해당 키를 사용하는 모든 연동을 업데이트하고 새 키로 정상적으로 작동하는지 확인해 주세요. 더 이상 필요하지 않을 때에만 원본을 삭제해 주세요.

쿼리 매개 변수 사용

include 매개 변수는 API 응답에 관련 데이터를 추가해요. scopes 매개 변수는 비공개 API 키 생성 페이지에서 권한을 미리 선택해요. 이것들은 URL 쿼리 매개 변수의 별도 고급 사용 방법이에요. 익숙하지 않다면 개발자와 함께 작업해 주세요.

API 응답에 관련 데이터를 포함하기

엔드포인트가 include 쿼리 매개 변수를 지원하는 경우, 키에 요청된 리소스와 관련 데이터 모두를 읽을 수 있는 권한이 있어야 해요.

예를 들어, GET /api/profiles/{id}/는 단일 프로필을 가져오며 profiles:read이(가) 필요해요. {id}를 프로필의 ID로 바꿔 주세요.

해당 프로필의 리스트를 포함하려면 profiles:read 및 lists:read와 함께 GET /api/profiles/{id}/?include=lists을(를) 사용해 주세요. 프로필 컬렉션 엔드포인트(GET /api/profiles/)는 리스트 포함을 지원하지 않아요.

생성 페이지에서 범위를 미리 선택하기

양식에서 액세스 수준을 미리 선택하려면 비공개 API 키 생성 URL에 scopes 쿼리 매개 변수를 추가하세요.

범위(scope) 이름 목록을 쉼표로 구분하여 입력하세요. 선택한 액세스를 검토하고, 키 이름을 입력한 다음 만들기를 선택하세요. 그런 다음 확인 페이지를 닫기 전에 키를 복사하거나 다운로드하세요.

예시 URL은 다음과 같아요:
https://www.klaviyo.com/create-private-api-key?scopes=campaigns:read,campaigns:write

개발자 포털로 이동하여 이 쿼리에서 사용할 수 있는 범위를 확인하세요.

추가 자료