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

# 키 및 ID

> OneSignal App ID, Organization ID 및 API 키를 찾고 관리하는 방법을 알아봅니다. 키를 생성, 교체, 보호하고 안전하게 마이그레이션하는 방법을 설명합니다.

OneSignal 계정에는 **공개 ID**(App ID, Organization ID)와 **비공개 API 키**(앱 API 키, 조직 API 키)가 포함되어 있습니다.

* [앱 ID](#app-id)와 [조직 ID](#organization-id)는 공개 식별자이며, 클라이언트 측 코드와 SDK 초기화에 안전하게 사용할 수 있습니다.
* [앱 API 키](#app-api-key)와 [조직 API 키](#organization-api-key)는 비공개 비밀 정보입니다. 안전하게 저장하고 클라이언트 측 코드에 절대 노출하지 마세요.

OneSignal 대시보드의 **Settings > Keys & IDs**(앱 수준) 또는 **Organizations > 귀하의 조직 > Keys & IDs**(조직 수준)에서 확인할 수 있습니다.

***

## 앱 ID

**앱 ID**는 OneSignal 앱을 식별하는 공개 UUID(v4)입니다.

다음 용도로 사용합니다:

* SDK 초기화(모바일 SDK 설정, 웹 SDK 설정)
* 메시지 생성 및 사용자 생성과 같은 API 요청

대시보드의 **Settings > Keys & IDs**에서 또는 [앱 보기](/reference/view-apps) API를 통해 앱 ID를 확인할 수 있습니다.

<Frame caption="Settings > Keys & IDs에서의 앱 ID 위치">
  <img src="https://mintcdn.com/onesignal/W0DIQbUDatcgdZf6/images/dashboard/dashboard-keys-and-ids-app-id-number.jpg?fit=max&auto=format&n=W0DIQbUDatcgdZf6&q=85&s=07fa6040dbc41ffa7dff116a0b1ad575" alt="Keys & IDs 설정 페이지에서 강조 표시된 앱 ID 값" width="1375" height="528" data-path="images/dashboard/dashboard-keys-and-ids-app-id-number.jpg" />
</Frame>

<Check>
  앱 ID는 클라이언트 측 SDK 초기화에 안전하게 사용할 수 있습니다. 비밀 정보가 아닙니다.
</Check>

***

## 조직 ID

\*\*조직 ID(Org ID)\*\*는 청구 플랜에 따라 모든 앱을 그룹화하는 UUID(v4)입니다.

다음과 같은 조직 수준 API에 필요합니다:

* [앱 생성](/reference/create-an-app)
* [앱 업데이트](/reference/update-an-app)

**Organizations > 귀하의 조직 > Keys & IDs** 또는 [앱 보기](/reference/view-an-app) API를 통해 확인할 수 있습니다.

<Frame caption="OneSignal 대시보드에서의 조직 ID 위치">
  <img src="https://mintcdn.com/onesignal/MWGmj5X1CnFliD-c/images/dashboard/dashboard-keys-and-ids-organization-id.png?fit=max&auto=format&n=MWGmj5X1CnFliD-c&q=85&s=b28d6312569975a67ca3eb1be9f568e4" alt="Keys & IDs 아래에 조직 ID를 보여주는 OneSignal 대시보드" width="2560" height="1228" data-path="images/dashboard/dashboard-keys-and-ids-organization-id.png" />
</Frame>

***

## API 키

두 가지 종류의 API 키가 있습니다. 둘 다 REST API 요청을 인증하며 비밀로 유지되어야 합니다. 원하는 작업에 맞는 키를 선택하세요:

| 키                                 | 사용 용도                        |
| --------------------------------- | ---------------------------- |
| [앱 API 키](#app-api-key)           | 단일 앱: 메시지 전송, 사용자 생성, 통계 조회. |
| [조직 API 키](#organization-api-key) | 조직 전체: 앱 생성 및 다른 API 키 관리.   |

<Note>
  앱당 최대 16개의 앱 API 키와 조직당 최대 16개의 조직 API 키를 생성할 수 있습니다.
</Note>

### 앱 API 키

**앱 API 키**는 단일 앱으로 범위가 지정된 모든 REST API 요청에 사용합니다: 메시지 전송, 사용자 생성 또는 업데이트, 메시지 기록 조회 등.

대시보드는 기존 API 키 값을 표시하지 않습니다. 키 ID 열의 문자열은 내부 식별자일 뿐이며 키가 아닙니다. 다시 작동하는 비밀 키를 얻으려면 아래 단계에 따라 새 API 키를 생성하거나 [기존 키를 교체](#rotate-a-key)하세요. 교체하면 동일한 키 ID, 이름, IP 허용 목록을 유지하면서 새 값이 생성되고 이전 값은 즉시 작동을 멈춥니다.

<Frame caption="대시보드는 키 ID를 표시하며 API 키 값은 표시하지 않습니다. 실제 값(os_v2_app_로 시작)은 키가 생성되거나 교체될 때 한 번만 표시됩니다.">
  <img src="https://mintcdn.com/onesignal/yYUi2EK-maheXJet/images/dashboard/api-key-list.png?fit=max&auto=format&n=yYUi2EK-maheXJet&q=85&s=e6c8dcfa23dc56ec4a2de364ffdffd99" alt="API 키 값이 아닌 키 ID 열을 보여주는 OneSignal 대시보드의 API Keys 테이블" width="2728" height="1104" data-path="images/dashboard/api-key-list.png" />
</Frame>

**앱 API 키 생성**

다음 단계에 따라 대시보드에서 앱 API 키를 생성하거나 [API 키 생성](/reference/create-api-key) API를 사용하세요.

<Steps>
  <Step title="앱의 Settings > Keys & IDs로 이동합니다">
    OneSignal 대시보드에서 앱을 선택하고 **Settings > Keys & IDs**로 이동합니다.
  </Step>

  <Step title="Add Key를 클릭합니다">
    설명적인 이름을 입력합니다(예: `Backend service`). 키가 승인된 서버에서만 작동하도록 [IP 허용 목록](#ip-allowlist)을 선택적으로 추가할 수 있습니다.
  </Step>

  <Step title="Create를 클릭한 다음 키 값을 즉시 복사합니다">
    값은 `os_v2_app_`로 시작하며 **한 번만** 표시됩니다. 비밀 관리자나 백엔드 환경 변수에 즉시 저장하세요.

    <Frame caption="생성된 API 키 값, 한 번만 표시됨">
      <img src="https://mintcdn.com/onesignal/QOf62tdZP66tkOD2/images/docs/generated-api-key.png?fit=max&auto=format&n=QOf62tdZP66tkOD2&q=85&s=81c7a600d8d5f88b79c47a027acc0c41" alt="생성 후 표시된 생성된 API 키" width="764" height="768" data-path="images/docs/generated-api-key.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  앱 API 키를 비밀번호처럼 취급하세요:

  * 모바일 또는 웹 클라이언트 코드에 노출하지 마세요.
  * GitHub와 같은 공개 저장소에 커밋하지 마세요.
  * 보안 백엔드 또는 비밀 관리자에 저장하세요.
</Warning>

### 조직 API 키

**조직 API 키**는 조직 내 모든 앱에 걸친 작업에 사용합니다. 일반적인 엔드포인트:

* **앱 관리:** [앱 생성](/reference/create-an-app), [앱 보기](/reference/view-apps)
* **API 키 관리:** [API 키 생성](/reference/create-api-key), [API 키 삭제](/reference/delete-api-key), [API 키 교체](/reference/rotate-api-key)

**조직 API 키 생성:**

조직 API 키는 대시보드 전용입니다. 생성용 API 엔드포인트가 없습니다.

<Steps>
  <Step title="조직의 Keys & IDs로 이동합니다">
    OneSignal 대시보드에서 **Organizations > 귀하의 조직 > Keys & IDs**로 이동합니다.
  </Step>

  <Step title="Add Key를 클릭하고 이름을 지정합니다">
    설명적인 이름을 입력합니다(예: `App provisioning`). 선택적으로 [IP 허용 목록](#ip-allowlist)을 추가할 수 있습니다.
  </Step>

  <Step title="Create를 클릭한 다음 키 값을 즉시 복사합니다">
    값은 `os_v2_app_`로 시작하며 **한 번만** 표시됩니다. 즉시 안전하게 저장하세요.
  </Step>
</Steps>

<Frame caption="조직 API 키를 생성하는 조직 Keys & IDs 페이지">
  <img src="https://mintcdn.com/onesignal/W0DIQbUDatcgdZf6/images/dashboard/default-org-api-keys-and-ids.jpg?fit=max&auto=format&n=W0DIQbUDatcgdZf6&q=85&s=d014d99705d175a153d43444b42adca3" alt="Keys & IDs 대시보드의 조직 API 키 섹션" width="1846" height="840" data-path="images/dashboard/default-org-api-keys-and-ids.jpg" />
</Frame>

<Warning>
  조직 API 키는 조직의 모든 앱에 대한 액세스 권한을 부여합니다. 각별한 주의를 기울이고, 조직 전체 액세스가 진정으로 필요한 서비스와만 공유하세요.
</Warning>

***

## IP 허용 목록

IP 허용 목록은 선택 사항이지만 강력히 권장됩니다. API 키 사용을 특정 IP 주소로 제한하여 유출된 키가 다른 곳에서 사용되지 않도록 합니다.

* 공백으로 구분된 CIDR 블록을 입력합니다(예: `192.0.2.0/24 192.0.2.123/32`).
* 허용되지 않은 IP의 요청은 거부됩니다.

IP 허용 목록은 다음에 사용합니다:

* 고정 IP를 가진 백엔드 서비스.
* 높은 보안이 필요한 프로덕션 환경.

<Frame caption="IP 허용 목록이 활성화된 API 키 생성">
  <img src="https://mintcdn.com/onesignal/QOf62tdZP66tkOD2/images/docs/ip-allowlist-config.png?fit=max&auto=format&n=QOf62tdZP66tkOD2&q=85&s=d2bdf5bec27c8a982c027d428687a3b9" alt="API 키 생성 모달의 IP 허용 목록 구성 필드" width="764" height="542" data-path="images/docs/ip-allowlist-config.png" />
</Frame>

***

## API 키 관리

키를 생성한 후 **Settings > Keys & IDs**의 키 목록에서 편집, 교체 또는 삭제할 수 있습니다. 앱 API 키는 REST API를 통해서도 이러한 작업을 지원합니다. 조직 API 키는 대시보드 전용입니다.

### 키 편집

비밀 값을 변경하지 않고 이름 또는 IP 허용 목록을 업데이트합니다. 통합 변경이 필요하지 않습니다.

대시보드 또는 [API 키 업데이트](/reference/update-api-key) API를 사용하세요(앱 API 키만 해당).

### 키 교체

교체하면 동일한 키 ID, 이름, IP 허용 목록을 유지하면서 새 비밀 값이 생성됩니다. 이전 비밀 값은 즉시 작동을 멈춥니다.

다음과 같은 경우 키를 교체하세요:

* 키가 노출된 경우.
* 액세스 권한이 있는 팀원이 퇴사한 경우.
* 정기 보안 교체 시기가 된 경우.
* 원래 키 값을 분실하여 작동하는 비밀 값이 필요한 경우.

<Warning>
  키를 교체한 후 이전 값을 사용하는 모든 서비스를 업데이트하세요. 이전 키로의 요청은 즉시 실패합니다.
</Warning>

대시보드 또는 [API 키 교체](/reference/rotate-api-key) API를 사용하세요(앱 API 키만 해당).

### 키 삭제

삭제는 키를 영구적으로 제거하고 해당 키를 사용하는 API 액세스를 즉시 차단합니다. 키가 더 이상 필요하지 않을 때 삭제를 사용하세요.

대시보드 또는 [API 키 삭제](/reference/delete-api-key) API를 사용하세요(앱 API 키만 해당).

***

## 레거시 API 키에서 마이그레이션

OneSignal은 이름 지정, 교체, IP 허용 목록을 갖춘 앱 및 조직 API 키를 2024년 11월에 도입했습니다. 레거시 User Auth key와 원래 REST API 키는 계속 사용할 수 있지만, 이를 위한 관리 UI는 제거되었고 새 키를 생성할 수 없습니다.

<Steps>
  <Step title="새 키 생성">
    교체하려는 레거시 키에 따라 새 [앱 API 키](#app-api-key) 또는 [조직 API 키](#organization-api-key)를 생성합니다.
  </Step>

  <Step title="코드 업데이트">
    OneSignal에 대해 인증하는 모든 서비스에서 레거시 키를 새 값으로 교체합니다.
  </Step>

  <Step title="API 기본 URL 업데이트">
    API 기본 URL을 `https://onesignal.com/api/v1/`에서 `https://api.onesignal.com`으로 변경합니다.
  </Step>

  <Step title="검증 후 레거시 키 비활성화">
    스테이징 환경에서 API 요청을 테스트한 다음 **Settings > Keys & IDs**에서 레거시 키를 비활성화하거나 삭제합니다.
  </Step>
</Steps>

<Check>
  프로덕션에서 레거시 키를 비활성화하기 전에 스테이징 환경에서 API 요청을 검증하세요.
</Check>

***

## API 액세스 차단

키를 즉시 취소하려면 **Settings > Keys & IDs**에서 [교체](#rotate-a-key)하거나 [삭제](#delete-a-key)하세요. 이전 값을 사용하는 요청은 즉시 실패합니다.

메시지 전송을 중지하거나 앱을 완전히 일시 중지하려면 [비활성화된 앱 및 조직](./disabled-apps)을 참조하세요.

***

## 보안 모범 사례

* API 키를 보안 백엔드에 저장하세요(클라이언트 측에 저장하지 마세요).
* 환경 변수 또는 비밀 관리자를 사용하세요.
* 가능한 경우 IP 허용 목록을 활성화하세요.
* 주기적으로 키를 교체하세요.
* 스테이징과 프로덕션에 별도의 키를 사용하세요.

***

## 자주 묻는 질문

### API 키는 어디서 찾을 수 있나요?

API 키 값은 `os_v2_app_`로 시작하며 키 생성 또는 교체 직후에 한 번만 표시됩니다. 대시보드의 **키 ID** 열은 내부 식별자이며 API 키가 아닙니다. 인증에 사용하면 `401 Unauthorized`를 반환합니다. 키 값을 저장하지 않은 경우 [키를 교체](#rotate-a-key)하여 새 값을 생성하세요. 전체 흐름은 [앱 API 키](#app-api-key) 또는 [조직 API 키](#organization-api-key)를 참조하세요.

### 레거시 앱 API 키를 복구할 수 있나요?

아니요. OneSignal은 더 이상 레거시 앱 API 키를 표시하지 않습니다. 코드베이스에서 값을 찾을 수 없는 경우 새 앱 API 키를 생성하고 통합을 업데이트하세요.

### 앱 ID, 앱 API 키, 조직 API 키의 차이점은 무엇인가요?

* **앱 ID**: 앱의 공개 식별자입니다. SDK 설정과 앱을 지정하는 API 요청에 사용됩니다.
* **앱 API 키**: 하나의 앱에서 메시지를 전송하고 사용자를 관리하는 데 사용되는 비밀 키입니다.
* **조직 API 키**: 전체 계정의 앱과 조직 수준 설정을 관리하는 데 사용되는 비밀 키입니다.

### API 키가 노출되면 어떻게 되나요?

즉시 [키를 교체](#rotate-a-key)하세요. 교체는 이전 값을 무효화하고 동일한 키 ID, 이름, IP 허용 목록을 유지하면서 새 값을 발급합니다. 그런 다음 해당 키를 사용하는 모든 서비스를 업데이트하세요. 예기치 않은 API 활동에 대한 [감사 로그](./audit-logs)를 검토하세요.

***

## 관련 페이지

<Columns cols={2}>
  <Card title="REST API 개요" icon="code" href="/reference/rest-api-overview">
    요청을 인증하고 OneSignal REST API를 이해합니다.
  </Card>

  <Card title="속도 제한" icon="clock" href="/reference/rate-limits">
    키별 속도 제한 및 대용량 통합을 위한 모범 사례.
  </Card>

  <Card title="감사 로그" icon="file-shield" href="./audit-logs">
    키, 사용자 및 시간별로 API 및 대시보드 활동을 검토합니다.
  </Card>

  <Card title="비활성화된 앱 및 조직" icon="ban" href="./disabled-apps">
    앱을 일시 중지하거나 종료하고 청구 영향을 이해합니다.
  </Card>
</Columns>