API 액세스 토큰

API 액세스 토큰은 계정의 특정 프로젝트 또는 여러 프로젝트에 할당된 고유 식별자입니다. API를 통해 프로젝트를 관리하기 위해 계정을 인증하며, 계정 수정, 메시지 전송, 프로젝트 편집 등을 포함합니다.

API 액세스 토큰 유형

Pushwoosh는 **서버(Server)**와 디바이스(Device) 두 가지 다른 API 액세스 토큰 유형을 제공합니다.

각 토큰 유형은 특정 API 범위에만 유효합니다. 잘못된 토큰을 사용하면 인증 오류가 발생합니다.

서버 API 토큰

서버 API 토큰은 디바이스 API에 속한 메서드를 제외한 모든 API 메서드와 함께 사용됩니다. 요청 본문의 auth 필드에 포함되어야 합니다.

디바이스 API 토큰

디바이스 API 토큰은 디바이스 API 메서드에서만 독점적으로 사용됩니다. HTTP 요청 헤더의 Authorization 헤더를 사용하여 포함되어야 합니다. 아래는 올바른 헤더 형식의 예시입니다:

Authorization: Token <device_api_token>

<device_api_token>을 실제 디바이스 API 토큰 값으로 바꾸세요.

API 액세스 토큰 생성 및 관리

Pushwoosh 제어판의 API 액세스 섹션에서 API 액세스 토큰을 보고, 생성하고, 관리할 수 있습니다. 액세스하려면 설정 → API 액세스로 이동하세요. Pushwoosh Demo App token

기본적으로 각 계정에는 서버 토큰으로 설정된 Pushwoosh Demo App이라는 토큰이 포함되어 있습니다.

새 API 액세스 토큰 생성

새 API 액세스 토큰을 생성하려면:

제어판의 API 액세스 섹션으로 이동합니다.
새 토큰 생성을 클릭합니다.
나타나는 창에서 토큰 유형을 선택합니다:
- 대부분의 API 메서드(디바이스 API 메서드 제외)에 사용되는 서버.
- 디바이스 API 메서드에만 사용되는 디바이스.
토큰의 이름을 입력합니다.
생성을 클릭하여 토큰을 만듭니다.

Generate a New Token

중요: Pushwoosh 제어판에서 토큰에 올바른 앱에 대한 액세스 권한을 부여해야 합니다. 자세히 알아보기

새 토큰이 API 액세스 목록에 나타납니다. 여기에서 API 요청에 사용할 값을 복사하거나 필요에 따라 액세스 권한을 관리할 수 있습니다.

토큰 관리

기존 API 토큰을 관리하려면 API 액세스 섹션의 토큰 항목 옆에 있는 **세 점 메뉴(⋮)**를 클릭합니다.

Manage a token

다음 옵션을 사용할 수 있습니다:

모든 프로젝트에 액세스 권한 부여

토큰에 계정의 모든 프로젝트에 대한 액세스 권한을 부여합니다. 이를 통해 모든 프로젝트에서 API를 완전히 사용할 수 있습니다.

모든 프로젝트에서 액세스 권한 철회

계정의 모든 프로젝트에 대한 토큰의 액세스 권한을 제거합니다. 액세스 권한이 다시 부여될 때까지 토큰은 더 이상 API를 사용할 수 없습니다.

토큰 편집

API 토큰 권한 편집 화면을 열어 다음을 수행할 수 있습니다:

토큰 이름 변경
토큰 값 복사
목록에서 프로젝트를 선택하거나 선택 취소하여 토큰이 액세스할 수 있는 프로젝트 선택
토큰의 권한 켜기 또는 끄기: 계정 수정, 애플리케이션 수정, 태그 수정, 메시지 전송 및 삭제
토큰을 사용할 수 있는 허용된 IP 주소 설정 (서버 토큰만 해당)

권한 탭에는 토큰이 마지막으로 사용된 시간과 지난 7일 및 30일 동안 거부된 호출 수가 표시됩니다.

Edit token screen with Permissions and Usage journal tabs, usage summary, and Allowed IP addresses field

변경을 마친 후 저장을 클릭하여 적용합니다.

토큰 사용 기록 확인

API 토큰 권한 편집 화면에서 사용 기록 탭을 열어 지난 90일 동안 토큰으로 이루어진 모든 API 호출을 검토합니다. 결과(모든 결과, 수락됨, 완료됨, 거부됨: IP 주소, 거부됨: 권한 없음)와 날짜 범위를 선택한 다음 적용을 클릭하여 목록을 필터링합니다. CSV 내보내기를 클릭하여 필터링된 로그를 CSV 파일로 다운로드합니다.

Usage journal tab with outcome and date filters and a CSV export button

토큰 삭제

계정에서 토큰을 영구적으로 제거합니다.

API 요청 인증

API 요청을 인증하려면 호출하는 API 메서드 유형에 따라 올바른 유형의 API 액세스 토큰을 사용하세요:

서버 API 메서드의 경우

요청 본문의 “auth” 필드에 토큰을 포함시키세요:

예시:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "yxoPUlwqm…………pIyEX4H", // 여기에 서버 토큰을 붙여넣으세요
    "notifications": [{
      "send_date": "now",
      "content": "Hello world"
    }]
  }
}

디바이스 API 메서드의 경우

디바이스 토큰을 사용하세요. 다음 형식을 사용하여 HTTP 요청 헤더에 포함시키세요:

Authorization: Token <device_api_token>

<device_api_token>을 실제 토큰 값으로 바꾸세요.

특정 IP 주소로 토큰 제한

서버 토큰은 허용된 소스 IP 주소 목록으로 제한될 수 있습니다. 목록이 설정되면 Pushwoosh는 해당 토큰으로 일치하는 주소에서 온 API 요청만 수락합니다. 디바이스 토큰에는 이 옵션이 없습니다.

서버 토큰에 대해 토큰 편집을 열고 허용된 IP 주소에 주소를 입력하세요:

최대 50개의 항목을 추가할 수 있으며, IPv4 또는 IPv6, 각 항목은 단일 주소(203.0.113.7) 또는 CIDR 범위(203.0.113.0/24)입니다.
단일 주소는 전체 길이 범위로 저장됩니다. 예: 203.0.113.7은 203.0.113.7/32가 됩니다.
범위는 네트워크 주소로 정규화됩니다. 예: 203.0.113.7/24는 203.0.113.0/24가 됩니다.
0.0.0.0/0 및 ::/0은 모든 주소와 일치하여 제한을 제공하지 않으므로 거부됩니다.
목록을 비워두면 모든 주소에서 토큰을 사용할 수 있습니다. 이는 기존 토큰과 새 토큰의 기본값입니다.

저장을 클릭하여 목록을 적용합니다. 목록에 50개 이상의 항목이 있거나 유효한 주소 또는 CIDR 범위가 아닌 항목이 있는 경우 저장이 거부됩니다.

허용되지 않은 주소에서 요청이 올 때 발생하는 일

Pushwoosh는 토큰으로 이루어진 모든 API 호출에서 허용된 IP 주소를 확인합니다. 이는 이 API 참조 전체에 문서화된 v1 REST 호출(예: 메시지 API), 메시징 API v2 호출 또는 고객 여정 API 호출 여부와 관계없이 적용됩니다. 토큰의 허용 목록에 없는 주소에서 온 요청은 거부됩니다.

응답 형식은 어떤 호출을 하느냐에 따라 다릅니다:

메시지 전송, 취소 및 삭제(예: createMessage, 채널별 create*Message 메서드, cancelMessage, deleteMessage)는 다른 인증 실패와 마찬가지로 응답 본문에 "status_code": 403과 함께 HTTP 200을 반환합니다.
애플리케이션, 태그, 지오존, 세분화(필터), 캠페인, 프리셋, 테스트 디바이스 및 통계 API와 같은 다른 v1 REST 호출은 JSON 오류 본문과 함께 실제 HTTP 403을 반환합니다.
메시징 API v2 및 고객 여정 API는 PermissionDenied 오류와 함께 HTTP 403을 반환합니다.