메인 콘텐츠로 건너뛰기
MeterEngine은 사람이 쓰는 콘솔 로그인과 도입사 서버가 쓰는 API 키로 인증합니다. 둘 다 read, ingest, admin 권한으로 할 수 있는 일이 정해지지만, 몇몇 기능은 콘솔 로그인으로만 됩니다.

​
콘솔 로그인과 API 키

콘솔 화면에도 “API 키는 서버의 권한입니다. 사람의 관리 권한은 사용자 관리에서 정합니다.”라고 쓰여 있습니다. 사람의 권한을 바꿔도 그 사람이 발급한 키의 권한은 바뀌지 않고, 키를 폐기해도 사람의 권한은 그대로입니다. 키 발급 방법은 API 키 발급과 첫 호출을 보세요.

​
read, ingest, admin

  • admin은 read와 ingest를 포함합니다. admin만 준 키로도 조회와 이벤트 전송을 할 수 있습니다.
  • read와 ingest는 서로 포함하지 않습니다. ingest만 준 키는 조회 요청에 403 permission_denied를 받습니다. 둘이 다 필요하면 함께 체크하세요.
  • 권한이 모자라면 403 permission_denied가 옵니다.

​
어떤 요청에 어떤 권한이 필요한가

규칙은 다음과 같습니다. 아래 “콘솔 로그인으로만 되는 기능”은 예외입니다.
  1. 조회(GET)는 read가 필요합니다.
  2. 고객 등록(POST /v1/customers)과 이벤트 전송(POST /v1/events, POST /v1/event-batches)은 ingest가 필요합니다.
  3. 그 밖의 변경(POST, PUT, PATCH, DELETE)은 admin이 필요합니다.
자주 쓰는 요청으로 보면 다음과 같습니다.
ingest만 준 키로 이미 등록한 external_id의 고객을 다시 등록하면 200 응답에 id, external_id, version만 채워지고 나머지는 null입니다. 이벤트에 쓸 고객 id는 이 응답으로도 얻을 수 있습니다(고객 등록과 ID 대응).

​
콘솔 로그인으로만 되는 기능

아래 기능은 콘솔에 로그인한 상태에서만 됩니다. API 키로 부르면 admin 권한이 있어도 403 permission_denied로 거절됩니다. 이 가이드도 이 기능들은 콘솔 화면 절차로 안내합니다.
  • 토스페이먼츠 키 목록과 지금 결제 모드는 read 권한 API 키로도 조회할 수 있습니다(GET /v1/toss-payments-credentials, GET /v1/payment-setting). 저장과 변경만 콘솔에서 합니다.
  • 사용자와 초대 관리는 대표관리자만 할 수 있습니다. 자세한 내용은 구성원과 권한을 보세요.
  • 결제 모드를 바꿀 수 있는 경우는 테스트 결제와 실결제를 보세요.

​
API로만 되는 기능

사용량 이벤트 전송은 API로만 합니다. 콘솔에는 이벤트를 입력하는 화면이 없고, ‘수집 로그’ 화면에서 받은 이벤트를 조회만 합니다. 고객 등록은 콘솔과 API 둘 다 됩니다. 이벤트 보내는 법은 사용량 이벤트 보내기를 보세요.

​
MeterEngine 운영자만 하는 일

가입 신청 승인과 거절, 도입사 정지는 MeterEngine 운영자가 합니다. 도입사의 콘솔 로그인이나 API 키로는 할 수 없습니다. 승인 전이거나 거절, 정지된 도입사는 403 organization_not_active를 받습니다(가입과 승인).

​
권한을 바꾸면

  • 사람의 업무 권한과 키의 권한 모두 바꾼 뒤 다음 요청부터 적용됩니다. 다시 로그인하거나 키를 새로 넣지 않아도 됩니다.
  • 키 권한을 바꾸는 법은 키 교체, 권한 변경, 폐기를 보세요.
  • 구성원을 추가할 때 기본 권한은 조회(read)입니다(구성원과 권한).

​
권장하는 키 배분

키는 쓰는 서버마다 따로 발급하고, 그 서버가 하는 일에 필요한 권한만 주세요. 한 키가 새어 나가도 피해 범위가 그 권한으로 좁혀지고, 한 서버의 키만 바꿀 수 있습니다.
고객 등록과 이벤트 전송만 하면 ingest만 줍니다. 등록한 고객을 external_id로 다시 찾는 조회(GET /v1/customers?external_id=)도 하려면 read를 더합니다.
고객 포털처럼 사용량, 청구 예정액, 인보이스를 읽기만 하면 read만 줍니다.
인보이스 확정, 결제 요청, 링크 발급을 하면 admin이 필요합니다. admin 키는 고객 보관, 미터 변경 같은 모든 데이터 변경을 할 수 있으므로 이 서버에서만 쓰고 분당 요청 한도를 정해 두세요.
키는 발급한 업무 환경에 고정됩니다. 같은 서버라도 테스트 환경 키(me_test_)와 실제 환경 키(me_live_)를 따로 발급해 설정을 나눠 두세요(업무 환경).