> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meterengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 키 발급과 첫 호출

> 콘솔에서 서버 연동 키를 발급하고 첫 요청으로 키와 업무 환경을 확인합니다.

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

> [!NOTE]
>
> API 키 발급과 관리는 콘솔에 로그인한 상태에서만 됩니다. API 키로 부르면 거절됩니다. 콘솔 로그인과 API 키의 차이는 [화면과 API, 권한](https://docs.meterengine.com/authentication/scopes.md)을 보세요.

## 누가 발급하나

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

## 키의 형식

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

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

## 키 발급하기

**1. 업무 환경을 확인한다**

로그인 뒤 화면 위 '업무 환경'이 '테스트 환경'인지 확인하세요. 키는 발급한 업무 환경에 고정됩니다. 연동을 처음 시험할 때는 테스트 환경에서 발급하고, 실제 환경 키는 실제 환경으로 전환한 뒤 따로 발급합니다. 업무 환경을 바꾸는 법은 [업무 환경](https://docs.meterengine.com/concepts/environments.md)을 보세요.

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

**2. 'API 키와 통보' 화면을 연다**

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

**3. 키 이름과 권한, 한도를 정한다**

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

**4. 원문을 복사해 보관한다**

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

> [!WARNING]
>
> 창을 닫으면 원문을 다시 볼 수 없습니다. 원문을 잃었다면 새 키를 발급하고 옛 키는 교체하거나 폐기합니다([키 교체, 권한 변경, 폐기](https://docs.meterengine.com/authentication/key-rotation.md)).

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

## 첫 호출로 확인하기

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

```bash curl theme={null}
curl -i https://meterengine.com/v1/organization/environments \
  -H "Authorization: Bearer me_test_xxxxxxxx"
```

```javascript Node (fetch) theme={null}
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 응답 theme={null}
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"}]}
```

**environments** `object[]`

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

**항목**

**id** `string (UUID)`

업무 환경 id입니다.

**mode** `string`

`test` 또는 `live`입니다.

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

### 응답에 따라 할 일

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

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

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

오류 형식과 다시 보낼지 판단하는 법은 [오류 응답과 X-Request-ID](https://docs.meterengine.com/api-basics/errors.md)에 있습니다.

## 키 목록 읽기

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

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

> [!TIP]
>
> API 참조의 시험 화면에는 테스트 환경 키(`me_test_`)만 넣으세요. 시험 화면에서 보낸 요청은 Mintlify 서버를 거쳐 갑니다. 자세한 내용은 [API 참조 읽는 법](https://docs.meterengine.com/api-reference/introduction.md)을 보세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.