- 앱 ID와 조직 ID는 공개 식별자이며, 클라이언트 측 코드와 SDK 초기화에 안전하게 사용할 수 있습니다.
- 앱 API 키와 조직 API 키는 비공개 비밀 정보입니다. 안전하게 저장하고 클라이언트 측 코드에 절대 노출하지 마세요.
앱 ID
앱 ID는 OneSignal 앱을 식별하는 공개 UUID(v4)입니다. 다음 용도로 사용합니다:- SDK 초기화(모바일 SDK 설정, 웹 SDK 설정)
- 메시지 생성 및 사용자 생성과 같은 API 요청
앱 ID는 클라이언트 측 SDK 초기화에 안전하게 사용할 수 있습니다. 비밀 정보가 아닙니다.
조직 ID
**조직 ID(Org ID)**는 청구 플랜에 따라 모든 앱을 그룹화하는 UUID(v4)입니다. 다음과 같은 조직 수준 API에 필요합니다: Organizations > 귀하의 조직 > Keys & IDs 또는 앱 보기 API를 통해 확인할 수 있습니다.
API 키
두 가지 종류의 API 키가 있습니다. 둘 다 REST API 요청을 인증하며 비밀로 유지되어야 합니다. 원하는 작업에 맞는 키를 선택하세요:앱당 최대 16개의 앱 API 키와 조직당 최대 16개의 조직 API 키를 생성할 수 있습니다.
앱 API 키
앱 API 키는 단일 앱으로 범위가 지정된 모든 REST API 요청에 사용합니다: 메시지 전송, 사용자 생성 또는 업데이트, 메시지 기록 조회 등. 대시보드는 기존 API 키 값을 표시하지 않습니다. 키 ID 열의 문자열은 내부 식별자일 뿐이며 키가 아닙니다. 다시 작동하는 비밀 키를 얻으려면 아래 단계에 따라 새 API 키를 생성하거나 기존 키를 교체하세요. 교체하면 동일한 키 ID, 이름, IP 허용 목록을 유지하면서 새 값이 생성되고 이전 값은 즉시 작동을 멈춥니다.
Add Key를 클릭합니다
설명적인 이름을 입력합니다(예:
Backend service). 키가 승인된 서버에서만 작동하도록 IP 허용 목록을 선택적으로 추가할 수 있습니다.
조직 API 키
조직 API 키는 조직 내 모든 앱에 걸친 작업에 사용합니다. 일반적인 엔드포인트: 조직 API 키 생성: 조직 API 키는 대시보드 전용입니다. 생성용 API 엔드포인트가 없습니다.Add Key를 클릭하고 이름을 지정합니다
설명적인 이름을 입력합니다(예:
App provisioning). 선택적으로 IP 허용 목록을 추가할 수 있습니다.
IP 허용 목록
IP 허용 목록은 선택 사항이지만 강력히 권장됩니다. API 키 사용을 특정 IP 주소로 제한하여 유출된 키가 다른 곳에서 사용되지 않도록 합니다.- 공백으로 구분된 CIDR 블록을 입력합니다(예:
192.0.2.0/24 192.0.2.123/32). - 허용되지 않은 IP의 요청은 거부됩니다.
- 고정 IP를 가진 백엔드 서비스.
- 높은 보안이 필요한 프로덕션 환경.
API 키 관리
키를 생성한 후 Settings > Keys & IDs의 키 목록에서 편집, 교체 또는 삭제할 수 있습니다. 앱 API 키는 REST API를 통해서도 이러한 작업을 지원합니다. 조직 API 키는 대시보드 전용입니다.키 편집
비밀 값을 변경하지 않고 이름 또는 IP 허용 목록을 업데이트합니다. 통합 변경이 필요하지 않습니다. 대시보드 또는 API 키 업데이트 API를 사용하세요(앱 API 키만 해당).키 교체
교체하면 동일한 키 ID, 이름, IP 허용 목록을 유지하면서 새 비밀 값이 생성됩니다. 이전 비밀 값은 즉시 작동을 멈춥니다. 다음과 같은 경우 키를 교체하세요:- 키가 노출된 경우.
- 액세스 권한이 있는 팀원이 퇴사한 경우.
- 정기 보안 교체 시기가 된 경우.
- 원래 키 값을 분실하여 작동하는 비밀 값이 필요한 경우.
키 삭제
삭제는 키를 영구적으로 제거하고 해당 키를 사용하는 API 액세스를 즉시 차단합니다. 키가 더 이상 필요하지 않을 때 삭제를 사용하세요. 대시보드 또는 API 키 삭제 API를 사용하세요(앱 API 키만 해당).레거시 API 키에서 마이그레이션
OneSignal은 이름 지정, 교체, IP 허용 목록을 갖춘 앱 및 조직 API 키를 2024년 11월에 도입했습니다. 레거시 User Auth key와 원래 REST API 키는 계속 사용할 수 있지만, 이를 위한 관리 UI는 제거되었고 새 키를 생성할 수 없습니다.프로덕션에서 레거시 키를 비활성화하기 전에 스테이징 환경에서 API 요청을 검증하세요.
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 활동에 대한 감사 로그를 검토하세요.관련 페이지
REST API 개요
요청을 인증하고 OneSignal REST API를 이해합니다.
속도 제한
키별 속도 제한 및 대용량 통합을 위한 모범 사례.
감사 로그
키, 사용자 및 시간별로 API 및 대시보드 활동을 검토합니다.
비활성화된 앱 및 조직
앱을 일시 중지하거나 종료하고 청구 영향을 이해합니다.