메인 콘텐츠로 건너뛰기
OneSignal 계정에는 공개 ID와 비공개 API 키가 포함되어 있습니다.
  • ID(예: 앱 ID)는 SDK를 구성하고 앱을 참조하는 데 사용합니다.
  • API 키는 보안 REST API 요청을 인증하는 데 사용합니다.
이 가이드에서는 각 키의 역할, 찾는 위치, 안전하게 관리하는 방법을 설명합니다.

​
앱 ID

앱 ID는 OneSignal 앱을 식별하는 공개 UUID(v4)입니다. 다음 용도로 사용합니다:
  • SDK 초기화 (모바일 SDK 설정, 웹 SDK 설정)
  • 메시지 생성 및 사용자 생성과 같은 API 요청
대시보드의 설정 > 키 및 ID에서 또는 앱 보기 API를 통해 앱 ID를 확인할 수 있습니다.
앱 ID 위치를 보여주는 OneSignal 대시보드 키 및 ID 페이지.

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

​
조직 ID

**조직 ID(Org ID)**는 청구 플랜에 따라 모든 앱을 그룹화하는 UUID(v4)입니다. 다음과 같은 조직 수준 API에 필요합니다: 조직 > 귀하의 조직 > 키 및 ID 또는 앱 보기 API를 통해 확인할 수 있습니다.
키 및 ID 아래에 조직 ID를 보여주는 OneSignal 대시보드.

​
API 키 개요

OneSignal은 두 가지 유형의 API 키를 지원합니다:
키 유형범위용도
앱 API 키단일 앱메시지 전송, 사용자 생성, 앱 수준 작업
조직 API 키전체 조직앱 생성, API 키 관리, 조직 수준 구성
최대 16개의 API 키를 생성하고 IP 허용 목록을 구성할 수 있습니다.
두 키 모두 비공개 비밀 정보이므로 안전하게 저장해야 합니다.

​
앱 API 키

특정 앱과 관련된 대부분의 REST API 요청에 앱 API 키를 사용합니다. 인증 형식: key 인증 체계를 사용하여 Authorization 헤더에 키를 포함합니다: 
Authorization: key YOUR_REST_API_KEY
앱 설정 > 키 및 ID에서 또는 API 키 생성 API를 통해 앱 API 키를 생성할 수 있습니다.
앱 API 키를 비밀번호처럼 취급하세요.
  • 모바일 또는 웹 클라이언트 코드에 노출하지 마세요.
  • GitHub와 같은 공개 저장소에 커밋하지 마세요.
  • 보안 백엔드 또는 비밀 관리자에 저장하세요.

​
조직 API 키

조직 API 키는 다음 용도로 사용합니다: OneSignal 대시보드에서 조직 > 귀하의 조직 > 키 및 ID에서 생성합니다.
앱 API 키와 마찬가지로 최대 16개의 조직 키를 구성하고 IP 허용 목록 구성을 포함할 수 있습니다.

​
API 키 생성

대시보드에서 앱 및 조직 API 키를 모두 생성할 수 있습니다.
  • 앱 API 키는 API 키 생성 API를 통해서도 생성할 수 있습니다.
  • 조직 API 키는 대시보드에서만 생성할 수 있습니다.
키 생성 방법:
  1. 키 및 ID(앱 또는 조직 수준)로 이동합니다.
  2. 키 추가를 클릭합니다.
OneSignal 대시보드에서 새 API 키를 생성하는 모달.
  1. 설명적인 이름을 입력합니다(예: CRM 동기화 서비스).
  2. (선택 사항) IP 허용 목록을 구성합니다.
  3. 생성을 클릭합니다.
  4. 키를 즉시 복사하여 안전하게 저장합니다.
API 키는 한 번만 표시됩니다. 키를 분실한 경우 교체해야 합니다.

​
IP 허용 목록 (선택 사항이지만 권장)

API 키 사용을 특정 IP 주소로 제한할 수 있습니다.
  • 공백으로 구분된 CIDR 블록을 입력합니다.
    • 예: 192.0.2.0/24 192.0.2.123/32
  • 허용되지 않은 IP의 요청은 거부됩니다.
IP 허용 목록은 다음에 사용합니다:
  • 고정 IP를 가진 백엔드 서비스
  • 높은 보안이 필요한 프로덕션 환경
API 키 생성 모달의 IP 허용 목록 구성 필드.

​
키 관리

키를 생성한 후 키 목록 인터페이스를 통해 관리할 수 있습니다:
키 이름과 ID를 보여주는 OneSignal 대시보드의 API 키 목록.
키 ID는 참조용 레이블입니다. 비밀 API 키가 아닙니다.

​
API 키 편집

다음을 수행할 수 있습니다:
  • 키 이름 업데이트
  • IP 허용 목록 설정 수정
편집해도 비밀 값은 변경되지 않습니다. 통합 변경이 필요하지 않습니다.
  • 앱 API 키는 대시보드 또는 API 키 업데이트 API를 통해 업데이트할 수 있습니다.
  • 조직 API 키는 대시보드에서만 업데이트할 수 있습니다.

​
API 키 교체

키 교체 시:
  • 새로운 비밀 키가 생성됩니다
  • 동일한 이름 및 구성이 유지됩니다
  • 이전 비밀 키가 즉시 무효화됩니다
교체가 필요한 경우:
  • 키가 노출된 경우
  • 액세스 권한이 있는 팀원이 퇴사한 경우
  • 정기 보안 교체
키를 교체한 후 해당 키를 사용하는 모든 서비스를 업데이트하세요. 이전 키로의 요청은 실패합니다.
  • 앱 API 키는 대시보드 또는 API 키 교체 API를 통해 교체할 수 있습니다.
  • 조직 API 키는 대시보드에서만 교체할 수 있습니다.

​
API 키 삭제

키 삭제 시:
  • 영구적으로 제거됩니다
  • 해당 키를 사용한 API 액세스가 즉시 차단됩니다
더 이상 필요하지 않은 키에 대해 삭제를 사용합니다.
  • 앱 API 키는 대시보드 또는 API 키 삭제 API를 통해 삭제할 수 있습니다.
  • 조직 API 키는 대시보드에서만 삭제할 수 있습니다.

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

2024년 11월 14일에 풍부한 API 키 관리 기능을 도입했습니다. 마이그레이션 단계
  1. 새 앱 또는 조직 API 키를 생성합니다.
  2. 코드에서 레거시 키를 교체합니다.
  3. API 기본 URL을 다음으로 업데이트합니다:
https://api.onesignal.com
기존 URL 대신: 
https://onesignal.com/api/v1/
  1. 키 및 ID에서 레거시 키를 비활성화하거나 삭제합니다.
프로덕션에서 레거시 키를 비활성화하기 전에 스테이징 환경에서 API 요청을 테스트하세요.

​
앱 비활성화

API 액세스 차단:
  • API 키를 삭제하거나 교체하여 REST API 사용을 즉시 차단합니다.
메시지 전송 비활성화:
  • 설정 > 앱 관리 > 앱 비활성화로 이동합니다.
자세한 내용은 비활성화된 앱 및 조직을 참조하세요.
앱을 비활성화해도 청구가 중지되지 않습니다. 비활성화된 앱의 월간 활성 사용자(MAU)는 여전히 청구에 포함됩니다.청구를 중지하려면 앱을 삭제하거나 무료 조직으로 이동하세요.도움이 필요하면 support@onesignal.com에 문의하세요.

​
보안 모범 사례

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