API 키 발급과 첫 호출

도입사 서버가 MeterEngine API를 부를 때는 API 키로 인증합니다. 키는 콘솔의 ‘API 키와 통보’ 화면에서 발급하고, 요청마다 Authorization: Bearer <키> 헤더에 싣습니다.

API 키 발급과 관리는 콘솔에 로그인한 상태에서만 됩니다. API 키로 부르면 거절됩니다. 콘솔 로그인과 API 키의 차이는 화면과 API, 권한을 보세요.

누가 발급하나

키를 발급하려면 콘솔 사용자의 업무 권한에 admin(전체 관리)이 있어야 합니다. 이 권한이 없으면 ‘API 키 발급’ 버튼이 보이지 않습니다. 연동을 맡은 개발자에게 이 권한이 없다면 전체 관리(admin) 권한이 있는 구성원에게 키 발급을 요청해 원문을 안전한 경로로 받으세요. 업무 권한은 ‘사용자 관리’ 화면에서 정합니다(구성원과 권한).

키의 형식

항목	내용
형식	`me_test_` 또는 `me_live_` 뒤에 영문 대소문자와 숫자 32자
테스트 환경 키	`me_test_`로 시작합니다. 테스트 환경에서 발급합니다
실제 환경 키	`me_live_`로 시작합니다. 실제 환경에서 발급합니다
싣는 법	`Authorization: Bearer me_test_xxxxxxxx`
원문을 볼 수 있는 때	발급 직후 한 번. MeterEngine은 원문을 저장하지 않고 끝 네 글자만 보여 줍니다

API는 https://meterengine.com/v1/ 아래에 있고, 어느 환경에 기록될지는 API 키가 정합니다. 테스트 환경과 실제 환경의 주소는 같습니다. 자세한 내용은 API 참조 읽는 법을 보세요.

키 발급하기

업무 환경을 확인한다

로그인 뒤 화면 위 ‘업무 환경’이 ‘테스트 환경’인지 확인하세요. 키는 발급한 업무 환경에 고정됩니다. 연동을 처음 시험할 때는 테스트 환경에서 발급하고, 실제 환경 키는 실제 환경으로 전환한 뒤 따로 발급합니다. 업무 환경을 바꾸는 법은 업무 환경을 보세요.

업무 환경이 ‘기존 데이터’일 때는 API 키를 발급하지 마세요. 이때 나오는 키는 me_live_나 me_test_로 시작해도 테스트 환경과 실제 환경 어느 쪽에도 접근하지 못합니다. 발급 창에 ‘기존 키 구분’ 칸이 보이면 기존 데이터에 있는 것입니다.

'API 키와 통보' 화면을 연다

왼쪽 메뉴 ‘과금과 연동’의 ‘API 키와 통보’를 엽니다. ‘서버 연동 키’ 구역의 ‘API 키 발급’을 누릅니다.

키 이름과 권한, 한도를 정한다

‘키 이름’: 어느 서버가 쓰는 키인지 알아볼 이름입니다. 255자까지 씁니다(예: 사용량 전송 서버).
‘API 권한’: 기본으로 조회(read)만 체크되어 있습니다. 이벤트를 보내거나 고객을 등록할 키라면 수집(ingest)도 체크하세요. 권한별로 할 수 있는 일은 화면과 API, 권한에 있습니다.
‘분당 요청 한도’: 비우면 무제한입니다. 1 이상의 정수를 넣으면 이 키에 분당 요청 한도가 걸립니다. 한도를 세는 방식과 넘었을 때의 응답은 요청 한도와 429를 보세요.
‘교체할 기존 키’: 새로 발급할 때는 비워 둡니다. 쓰던 키를 바꿀 때 고르는 칸입니다(키 교체, 권한 변경, 폐기).

원문을 복사해 보관한다

발급하면 ‘이 창에서만 확인할 수 있습니다’라는 안내와 함께 키 원문이 나옵니다. ‘비밀값 복사’를 눌러 도입사 서버의 비밀 저장소에 옮긴 뒤 창을 닫으세요.

창을 닫으면 원문을 다시 볼 수 없습니다. 원문을 잃었다면 새 키를 발급하고 옛 키는 교체하거나 폐기합니다(키 교체, 권한 변경, 폐기).

API 키는 서버에서만 쓰는 비밀값입니다. 브라우저 화면, 모바일 앱, 공개 저장소의 코드에 넣지 마세요. 키를 가진 사람은 그 키의 권한으로 도입사의 데이터를 읽거나 바꿀 수 있습니다.

첫 호출로 확인하기

조회(read) 권한이 있는 키로 GET /v1/organization/environments를 보냅니다. 이 요청은 데이터를 바꾸지 않으므로 몇 번을 보내도 됩니다.

curl -i https://meterengine.com/v1/organization/environments \
  -H "Authorization: Bearer me_test_xxxxxxxx"

const response = await fetch("https://meterengine.com/v1/organization/environments", {
  headers: { Authorization: `Bearer ${process.env.METERENGINE_API_KEY}` },
});
console.log(response.status, response.headers.get("x-meterengine-environment"));
console.log(await response.json());

성공하면 200과 함께 도입사의 테스트 환경과 실제 환경이 옵니다. 응답 헤더 X-MeterEngine-Environment는 이 요청이 처리된 업무 환경이고, 테스트 환경 키라면 test입니다.

응답

HTTP/2 200
content-type: application/json
x-meterengine-environment: test
x-request-id: 3f2b8c1d-7e4a-4b6f-9d0c-5a1e2b3c4d5f

{"environments":[{"id":"0b6f3c1e-5d2a-4f7b-9c8e-1a2b3c4d5e6f","mode":"test"},{"id":"7d9e2f10-3b4c-4a5d-8e6f-7a8b9c0d1e2f","mode":"live"}]}

object[]

도입사의 업무 환경입니다. 테스트 환경이 먼저 옵니다.

표시 항목

string (UUID)

업무 환경 id입니다.

string

test 또는 live입니다.

키에 수집(ingest) 권한만 있으면 이 요청은 403 permission_denied를 받습니다. 키가 틀렸다면 401이 오므로, 403 permission_denied가 왔다면 키 자체는 인증된 것입니다. 수집 전용 키로 실제 동작까지 보려면 고객 등록과 ID 대응으로 이어 가세요.

응답에 따라 할 일

상태	code	뜻	할 일
401	`authentication_required`	`Authorization` 헤더가 없습니다	요청에 `Authorization` 헤더를 넣었는지 확인합니다
401	`invalid_credentials`	값 앞에 `Bearer` 가 없거나, 키 형식이 틀렸거나, 모르는 키이거나, 폐기 또는 만료된 키입니다	`Bearer` 접두사와 원문 전체를 넣었는지, ‘API 키와 통보’ 목록에서 키 상태가 ‘사용 중’인지 확인합니다
403	`permission_denied`	키 권한으로는 할 수 없는 요청입니다	필요한 권한은 화면과 API, 권한에서 확인합니다
403	`organization_not_active`	도입사가 활성 상태가 아닙니다	승인 전이거나 거절, 정지된 도입사는 이 응답을 받습니다(가입과 승인)
403	`environment_mismatch`	요청에 적은 업무 환경이 키의 환경과 다릅니다	키는 발급한 환경에 고정되어 `X-MeterEngine-Environment` 헤더를 따로 넣지 않아도 됩니다(업무 환경)

오류 응답 본문에는 code와 message가 실리고, 처리는 code로 나눕니다. 401 응답에는 WWW-Authenticate: Bearer 헤더도 붙습니다. 예를 들어 폐기한 키로 보내면 본문은 다음과 같습니다.

{"code":"invalid_credentials","message":"인증 정보가 올바르지 않습니다"}

오류 형식과 다시 보낼지 판단하는 법은 오류 응답과 X-Request-ID에 있습니다.

키 목록 읽기

‘API 키와 통보’ 화면의 키 목록은 지금 업무 환경에서 발급한 키만 보여 줍니다. ‘API 키 상태’에서 ‘사용 중’, ‘폐기됨’, ‘만료됨’, ‘전체’를 고를 수 있고, 처음에는 ‘사용 중’이 열립니다.

열	뜻
이름	발급할 때 붙인 ‘키 이름’
키 상태	’사용 중’, ‘폐기됨’, ‘만료됨’
API 키 구분	테스트 환경 키는 ‘테스트 키’, 실제 환경 키는 ‘운영 키’로 나옵니다
API 권한	키에 준 권한. ‘조회’, ‘수집’, ‘전체 관리’로 나옵니다
끝 네 글자	원문의 끝 네 글자. 서버에 넣은 키가 어느 것인지 맞춰 볼 때 씁니다
분당 한도	비어 있으면 ‘무제한’
만료 시각	교체한 키의 끝나는 시각. 교체하지 않은 키는 비어 있고, 기한 없이 쓸 수 있습니다
폐기 시각	폐기한 시각

API 참조의 시험 화면에는 테스트 환경 키(me_test_)만 넣으세요. 시험 화면에서 보낸 요청은 Mintlify 서버를 거쳐 갑니다. 자세한 내용은 API 참조 읽는 법을 보세요.

시작하기

개념

계정과 조직

인증

API 사용 기본

가격 설계

고객과 이벤트 연동

확인과 진단

청구 확정

결제 연동

웹훅

참고

API 키 발급과 첫 호출

누가 발급하나

키의 형식

키 발급하기

첫 호출로 확인하기

응답에 따라 할 일

키 목록 읽기

​누가 발급하나

​키의 형식

​키 발급하기

​첫 호출로 확인하기

​응답에 따라 할 일

​키 목록 읽기

누가 발급하나

키의 형식

키 발급하기

첫 호출로 확인하기

응답에 따라 할 일

키 목록 읽기