> ## 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 키를 끊김 없이 교체하고, 권한만 바꾸거나, 즉시 폐기하는 방법과 키가 새어 나갔을 때의 대응을 설명합니다.

> [!NOTE]
>
> 이 기능은 콘솔에 로그인한 상태에서만 됩니다. API 키로 부르면 거절됩니다. 모든 작업은 'API 키와 통보' 화면에서 하고, 콘솔 사용자의 업무 권한에 전체 관리(admin)가 있어야 합니다.

상황에 맞는 방법을 고르세요.

| 하려는 일 | 방법 | 옛 키는 |
| - | - | - |
| 정기적으로 키를 바꾼다, 담당자가 바뀌었다 | 교체 | 24시간 뒤 만료 |
| 권한만 늘리거나 줄인다 | '키 권한 변경' | 그대로 쓰고 원문도 같음 |
| 키가 새어 나갔다, 더 쓰지 않는다 | '키 폐기' | 즉시 사용 불가 |

## 키 교체

교체는 새 키를 발급하면서 옛 키에 끝나는 시각을 정하는 것입니다. 옛 키는 새 키를 발급한 때부터 24시간 동안 계속 쓸 수 있으므로, 그 사이에 서버들을 새 키로 옮기면 요청이 끊기지 않습니다.

**1. 옛 키와 같은 업무 환경으로 연다**

화면 위 '업무 환경'을 옛 키를 발급한 환경으로 맞추고 'API 키와 통보' 화면을 엽니다. 키 목록과 '교체할 기존 키' 선택지에는 지금 업무 환경의 '사용 중' 키만 나옵니다.

**2. 새 키를 발급하며 옛 키를 고른다**

'API 키 발급'을 누르고 '교체할 기존 키'에서 옛 키를 고릅니다. 선택지에는 '키 이름 (...끝 네 글자)'로 나옵니다.

> [!WARNING]
>
> 새 키는 옛 키의 권한과 분당 요청 한도를 물려받지 않습니다. 'API 권한'은 다시 조회(read)만 체크된 상태로 열리고 '분당 요청 한도'는 비어 있어 무제한입니다. 목록에서 옛 키의 'API 권한'과 '분당 한도'를 확인하고 같게 넣으세요. 특히 이벤트를 보내는 키라면 수집(ingest)을 빠뜨리지 마세요.

**3. 원문을 보관한다**

발급 창에 나온 원문을 '비밀값 복사'로 복사해 비밀 저장소에 넣습니다. 창을 닫으면 다시 볼 수 없습니다.

**4. 서버를 새 키로 옮긴다**

옛 키를 쓰는 모든 서버의 설정을 새 키로 바꿉니다. 바꾼 서버마다 새 키로 `GET /v1/organization/environments` 같은 조회를 한 번 보내 200이 오는지 확인하세요(수집 전용 키는 403 `permission_denied`가 오면 인증은 된 것입니다). 확인 방법은 [API 키 발급과 첫 호출](https://docs.meterengine.com/authentication/api-keys.md)에 있습니다.

**5. 옛 키의 만료 시각을 확인한다**

목록에서 옛 키의 '만료 시각'을 봅니다. 그 시각이 지나면 옛 키는 '만료됨'이 되고 요청은 401 `invalid_credentials`를 받습니다. 모든 서버를 그 전에 옮겼다면 기다리지 않고 옛 키를 '키 폐기'로 바로 끊어도 됩니다.

> [!WARNING]
>
> 24시간은 늘리거나 되돌릴 수 없습니다. 교체를 시작하면 옛 키는 만료 시각에 반드시 끝나고, 만료된 키를 다시 쓰게 할 방법은 없습니다. 같은 옛 키를 다른 새 키의 '교체할 기존 키'로 다시 골라도 만료 시각은 늦춰지지 않습니다. 서버를 옮길 준비가 된 뒤에 교체를 시작하세요.

> [accordion] 다른 업무 환경의 키로 교체할 수 없다
>
> 교체는 같은 업무 환경의 키끼리만 됩니다. 테스트 환경 키를 실제 환경 키로 바꾸는 것은 교체가 아닙니다. 실제 환경으로 전환해 새 키를 따로 발급하고, 테스트 환경 키는 테스트 환경에서 폐기하거나 그대로 둡니다.

> [accordion] 기존 데이터 범위의 키를 옮길 때
>
> 업무 환경 '기존 데이터'에서 발급한 키는 테스트 환경이나 실제 환경의 '교체할 기존 키'에 나오지 않습니다. 옮기려면 테스트 환경이나 실제 환경에서 새 키를 발급해 서버에 적용한 뒤, 업무 환경을 '기존 데이터'로 바꿔 옛 키를 폐기합니다. 새 키는 기존 데이터의 자료에 접근하지 못한다는 점도 확인하세요([업무 환경](https://docs.meterengine.com/concepts/environments.md)).

> [accordion] 키 이름이나 분당 한도만 바꾸고 싶을 때
>
> 발급한 키의 '키 이름'과 '분당 요청 한도'는 바꿀 수 없습니다. 바꾸려면 원하는 값으로 새 키를 발급하며 옛 키를 교체하세요.

## 키 권한 변경

키의 원문을 그대로 두고 권한만 바꿉니다. 서버 설정을 고치지 않아도 되며, 다음 요청부터 바뀐 권한이 적용됩니다.

**1. 키를 찾는다**

'API 키와 통보' 화면의 키 목록에서 바꿀 키 줄의 '키 권한 변경'을 누릅니다. '사용 중'인 키에만 이 동작이 있습니다.

**2. 권한을 고르고 저장한다**

'API 권한'을 고르고 '키 권한 저장'을 누릅니다. 하나 이상 골라야 합니다. 원문, 업무 환경, 만료 시각은 그대로입니다.

> [!WARNING]
>
> 권한을 줄이면 그 다음 요청부터 거절됩니다. 예를 들어 이벤트를 보내는 키에서 수집(ingest)을 빼면 이벤트 전송이 바로 403 `permission_denied`를 받습니다. 키를 쓰는 서버가 무엇을 부르는지 먼저 확인하세요. 권한별 허용 범위는 [화면과 API, 권한](https://docs.meterengine.com/authentication/scopes.md)에 있습니다.

폐기되었거나 만료된 키는 권한을 바꿀 수 없습니다. 이런 키가 필요하면 새로 발급합니다.

## 키 폐기

폐기한 키는 즉시 쓸 수 없습니다. 폐기한 뒤 그 키로 보낸 요청은 모두 401 `invalid_credentials`를 받습니다.

**1. 키를 찾는다**

'API 키와 통보' 화면의 키 목록에서 폐기할 키 줄의 '키 폐기'를 누릅니다. 이미 만료된 키도 폐기할 수 있습니다.

**2. 끝 네 글자를 확인한다**

확인 창에 '키 이름 (...끝 네 글자)'가 나옵니다. 서버에 넣은 키의 끝 네 글자와 맞춰 보고, 그 키를 쓰는 서버가 이미 새 키로 옮겼는지 확인하세요.

**3. 폐기한다**

> [!WARNING]
>
> 폐기는 되돌릴 수 없습니다. 아직 이 키로 이벤트를 보내는 서버가 있다면 그 요청은 401을 받고 저장되지 않습니다. 그동안 거절된 이벤트는 새 키로 다시 보내야 하니, 연동 쪽 재전송이 401을 받은 이벤트를 버리지 않는지 확인하세요([재전송 설계](https://docs.meterengine.com/integration/retries.md)).

'키 폐기'를 누릅니다. 키는 목록에서 사라지지 않고 'API 키 상태'를 '폐기됨'으로 고르면 '폐기 시각'과 함께 보입니다. 이미 폐기한 키를 다시 폐기해도 아무것도 바뀌지 않습니다.

## 키가 새어 나갔을 때

공개 저장소, 로그, 메신저 등에 키 원문이 노출되었다면 교체가 아니라 폐기부터 합니다. 교체는 옛 키를 24시간 더 살려 두기 때문입니다.

**1. 노출된 키를 바로 폐기한다**

'키 폐기'로 노출된 키를 끊습니다. 폐기한 순간부터 그 키의 요청은 401을 받습니다.

**2. 같은 권한으로 새 키를 발급한다**

'교체할 기존 키'는 비워 두고 새 키를 발급합니다. 'API 권한'과 '분당 요청 한도'를 옛 키와 같게, 또는 필요한 만큼만 줍니다.

**3. 서버에 새 키를 적용하고 빠진 이벤트를 다시 보낸다**

폐기와 적용 사이에 401로 거절된 이벤트가 있으면 새 키로 다시 보냅니다. 원래 `transaction_id`를 그대로 쓰세요. 같은 `transaction_id`로 다시 보내면 처음 것이 남으므로, 이미 저장된 이벤트가 섞여 있어도 두 번 세지 않습니다([멱등 규칙](https://docs.meterengine.com/api-basics/idempotency.md)).

**4. 기록을 확인한다**

키를 발급한 업무 환경에서 '감사 기록' 화면을 열어 'API 키 발급', 'API 키 권한 변경', 'API 키 폐기' 기록과, 실행 주체가 'API 키'인 'API 요청' 기록을 봅니다. 이벤트 전송 요청은 감사 기록에 남지 않고, '수집 로그'에도 어느 키로 보낸 이벤트인지는 나오지 않습니다. 모르는 이벤트가 들어왔는지는 '수집 로그'에서 고객과 기간으로 좁혀 확인하세요.

> [!NOTE]
>
> 보낸 이벤트는 고치거나 지울 수 없습니다. 노출된 키로 잘못된 이벤트가 들어왔다면 [사용량 이벤트 보내기](https://docs.meterengine.com/integration/events.md)의 정정 방법을 보세요.


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