키 및 ID

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

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

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

---

​

앱 ID

앱 ID는 OneSignal 앱을 식별하는 공개 UUID(v4)입니다. 다음 용도로 사용합니다:

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

대시보드의 Settings > Keys & IDs에서 또는 앱 보기 API를 통해 앱 ID를 확인할 수 있습니다.

---

​

조직 ID

**조직 ID(Org ID)**는 청구 플랜에 따라 모든 앱을 그룹화하는 UUID(v4)입니다. 다음과 같은 조직 수준 API에 필요합니다:

• 앱 생성
• 앱 업데이트

Organizations > 귀하의 조직 > Keys & IDs 또는 앱 보기 API를 통해 확인할 수 있습니다.

---

​

API 키

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

​

앱 API 키

앱 API 키는 단일 앱으로 범위가 지정된 모든 REST API 요청에 사용합니다: 메시지 전송, 사용자 생성 또는 업데이트, 메시지 기록 조회 등. 대시보드는 기존 API 키 값을 표시하지 않습니다. 키 ID 열의 문자열은 내부 식별자일 뿐이며 키가 아닙니다. 다시 작동하는 비밀 키를 얻으려면 아래 단계에 따라 새 API 키를 생성하거나 기존 키를 교체하세요. 교체하면 동일한 키 ID, 이름, IP 허용 목록을 유지하면서 새 값이 생성되고 이전 값은 즉시 작동을 멈춥니다. 앱 API 키 생성 다음 단계에 따라 대시보드에서 앱 API 키를 생성하거나 API 키 생성 API를 사용하세요.

​

조직 API 키

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

• 앱 관리: 앱 생성, 앱 보기
• API 키 관리: API 키 생성, API 키 삭제, API 키 교체

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

---

​

IP 허용 목록

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

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

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

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

---

​

API 키 관리

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

​

키 편집

비밀 값을 변경하지 않고 이름 또는 IP 허용 목록을 업데이트합니다. 통합 변경이 필요하지 않습니다. 대시보드 또는 API 키 업데이트 API를 사용하세요(앱 API 키만 해당).

​

키 교체

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

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

대시보드 또는 API 키 교체 API를 사용하세요(앱 API 키만 해당).

​

키 삭제

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

---

​

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

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

---

​

API 액세스 차단

키를 즉시 취소하려면 Settings > Keys & IDs에서 교체하거나 삭제하세요. 이전 값을 사용하는 요청은 즉시 실패합니다. 메시지 전송을 중지하거나 앱을 완전히 일시 중지하려면 비활성화된 앱 및 조직을 참조하세요.

---

​

보안 모범 사례

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

---

​

자주 묻는 질문

​

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

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

​

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

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

​

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

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

​

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

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

---

​

관련 페이지