API 인증 키는 KAS Console - Security - Credential 메뉴에서 발급받으며, 인증 비밀번호인 Secret AccessKey와 Authorization은 최초 생성 시 한 번만 확인할 수 있습니다. 따라서, 최초 생성 시 반드시 Secret AccessKey와 Authorization을 안전한 곳에 복사 또는 다운로드해 관리해야 합니다. 인증 키 생성시 확인할 수 있는 Authorization (예: Basic S0FTS1A2WkRaSjh...)은 Basic 인증 방식을 이용하여 AccessKey ID와 Secret AccessKey를 인코딩한 값이며 API 호출 시 호출 헤더에 사용합니다.
API 인증 키가 있으면 모든 KAS 서비스를 사용할 수 있으며 Wallet API를 호출해 만든 Klaytn 계정에 대한 모든 권한을 소유합니다. 모든 권한에는 Klaytn 계정의 자산(KLAY 등) 이동이나 트랜잭션 전송 및 실행 권한이 포함됩니다. 만약 API 인증 키에 타인이 접근한다면 Klaytn 계정 권한을 탈취당해 원치 않는 트랜잭션이 발생할 수 있습니다.
KAS/Klaytn 계정 보안을 위해 KAS API 인증 키(Secret Access Key)를 타인과 함부로 공유하지 말고 주의해 관리하십시오.
인증 키는 KAS 콘솔 - Security - Credential 메뉴에서 생성할 수 있습니다. 인증 키는 최대 2개까지 생성 가능합니다. 인증 키를 교체하려면 기존 키를 삭제하고 새 인증 키를 만들어야 합니다.
아래는 인증 키를 사용해 KAS API를 호출하는 예시입니다. 인증 키를 API 호출 헤더에 입력해야 하며 입력하는 방식은 아래와 같이 크게 2가지가 있습니다.
KAS API를 호출해 데이터를 불러올 때 모든 데이터를 한 번에 가져오기 어려울 때가 있습니다. 예를 들어, 여러분의 애플리케이션이 수천 개의 클레이튼 계정을 관리할 때 모든 계정 목록을 조회하려면 데이터를 한 번에 가져오기 어렵고 가져와도 데이터에 접근하기 불편합니다. 따라서, API를 여러 번 호출하여 지정된 개수만큼 데이터를 분할하여 불러오는데, 보통 데이터를 페이지 단위로 나눠 불러오기 때문에 이를 페이지네이션(Pagination)이라고 합니다.
KAS는 커서(Cursor) 기반 페이지네이션을 사용합니다. 어떤 KAS API가 쿼리 파라미터를 받을 때 size는 API 응답으로 받을 데이터 개수, cursor는 다음번 API 호출 시 이어서 받고 싶은 데이터 위치(offset)입니다.
먼저 API를 호출할 때 size를 입력하고 원하는 개수만큼 데이터를 받습니다. 그리고 API 응답값에 포함된 cursor값을 API를 다시 호출할 때 쿼리 파라미터로 입력하면 방금 받은 데이터 이후의 데이터를 이어 받을 수 있습니다.
다음은 여러분의 KAS에서 생성했던 클레이튼 계정 목록을 조회하는 API를 호출 시 페이지네이션을 사용해 계정 목록을 나누어 받는 예시를 소개합니다.
KRN (KAS Resource Name)은 KAS 모든 리소스를 식별하기 위한 고유한 값입니다. KAS에서 리소스란 여러분이 실제로 사용하려는 KAS 서비스에서 사용하는 자원(Preset, 계정, 수수료 대납 계정 등)을 의미합니다. 따라서 KAS는 내부적으로 여러분이 어떤 KAS 리소스에 접근하려고 할 때 KRN을 사용합니다.
KAS를 사용할 때 가장 빈번하게 접근하는 KAS 리소스 중 하나는 계정 저장소입니다. 여러분의 클레이튼 계정은 계정 저장소에 저장되어 있는데, KAS API를 호출할 때 특정 저장소에 있는 클레이튼 계정만을 사용하려면 반드시 이 저장소의 KRN값을 API 호출 헤더에 사용하셔야 합니다.
위 값은 KRN의 예시값입니다. krn:1001에서 1001은 체인 ID를 의미하며 여기서는 클레이튼 테스트넷인 Baobab을 의미합니다. 맨 마지막에 위치한 RayKim은 여러분이 만든 계정 저장소의 이름입니다. 여러분 자신만의 계정 저장소를 만들지 않고 KAS에서 기본 제공하는 계정 저장소에 클레이튼 계정을 만들 수도 있습니다. 이 때에는 계정 저장소 이름이 default가 됩니다.
여러분은 KAS API로 클레이튼에 트랜잭션을 보낼 수 있습니다. 이 때 특정 계정 저장소를 선택하고 이 저장소에 있는 계정으로 트랜잭션을 보낼 수 있습니다. 이렇게 특정 저장소의 특정 계정을 선택한 후 KAS API로 트랜잭션을 보내려면 이 저장소의 KRN값이 필요합니다.
위 API를 호출하면 RayKim이라는 계정 저장소에 있는 계정들 중에서 0x5bb85d4032354E88020595AFAFC081C24098202e라는 주소(EOA)를 가진 계정이 0x100만큼의 KLAY (단위:peb)를 0x2F87Ba64de5526F7880F21481Effbf950f70005c에게 전송합니다.
여러분의 수수료 대납 계정을 만들어서, 여러분의 다른 계정이 KAS로 Klaytn에 트랜잭션을 보낼 때 이 대납 계정으로 트랜잭션 수수료를 대신 납부하는 방식입니다. Klaytn에 트랜잭션을 전송하는 API를 호출할 때, feePayer 파라미터에 여러분이 준비한 대납 계정 주소를 입력합니다.
KAS에서 사용할 수수료 대납 계정은 반드시 KAS 콘솔에서 생성해야 합니다. KAS 콘솔에서 생성하지 않은 수수료 대납 계정은 KAS 콘솔에서 관리하지 않습니다.
KAS에서 여러분의 트랜잭션 수수료를 대신 납부하고, 추후 이 수수료만큼의 비용을 여러분 KAS 계정에 청구합니다. GlobalFeePayer란 KAS에서 제공하는 대납 계정이며 GlobalFeePayer를 사용하면 여러분이 트랜잭션 수수료 대납 계정과 수수료로 사용할 KLAY를 준비하지 않아도 수수료 대납 트랜잭션을 전송할 수 있습니다.
수수료 대납 방식 트랜잭션을 전송하는 API를 호출 시 feePayer 파라미터 자체를 입력하지 마십시오. KAS는 추후 여러분의 KAS 계정에 이 트랜잭션 전송 수수료 비용을 별도로 청구합니다.
KAS SDK(Software Development Kit)는 여러 개발 환경에서 KAS를 쉽게 사용하도록 제공되는 개발 도구입니다. KAS SDK는 Caver의 확장 라이브러리이며 Caver와 마찬가지로 JavaScript와 Java 환경을 지원합니다. KAS SDK로 BApp을 개발하면 하나의 라이브러리를 통해 KAS 기능과 기존 Caver의 기능을 모두 사용할 수 있습니다.