인증 토큰 API

앱 서버가 Hive Axyl Server API를 직접 호출할 때는 요청마다 JWT 액세스 토큰이 필요합니다. JWT 액세스 토큰은 요청을 보낸 주체와 대상 앱을 Hive Axyl 서버가 확인하는 데 사용하는 인증 정보입니다. 이 페이지에서는 앱 서버가 이 토큰을 발급받는 API와, 앱 클라이언트에서 받은 사용자의 액세스 토큰이 유효한지 확인하는 API를 설명합니다.

토큰 발급 준비

토큰을 발급받으려면 Hive 콘솔에서 발급한 보안 키가 필요합니다. 보안 키는 공개 식별자인 Client ID와 비밀 키인 Client Secret으로 구성합니다. 프로젝트 설정 > 보안 키에서 두 값을 확인하세요. 아직 보안 키를 발급하지 않았다면 보안 키를 참조하세요.

앱 서버용 토큰은 client_credentials 방식으로 발급합니다. 사용자 로그인 없이 Client ID와 Client Secret만으로 액세스 토큰을 받는 방식이며, 앱 서버와 Hive Axyl 서버 간 호출에 사용합니다. 이 토큰을 마스터 토큰이라고도 부릅니다.

Warning

Client Secret과 발급받은 액세스 토큰은 앱 서버에서만 보관하고 안전한 저장소에 두세요. 두 값이 앱 클라이언트에 포함되거나 외부에 노출되면 허가받지 않은 주체가 앱 서버를 대신해 API를 호출합니다.

토큰 발급

POST /token/v1/issue

Client ID와 Client Secret으로 앱 서버용 JWT 액세스 토큰을 발급받습니다. 다른 Hive Axyl Server API를 호출하기 전에 앱 서버에서 이 API를 먼저 호출하세요.

API 호출 전 준비

호출 주체: 앱 서버
기본 URL: https://core-api.hiveaxyl.com
인증: 필요하지 않음

호출 Parameters

이름	위치	타입	필수	설명
`X-App-Id`	`header`	`string`	`true`	Hive 콘솔에 등록한 App ID입니다. 헤더를 보내지 않으면 `missing_field`, 값이 비어 있으면 `missing_app_id`로 응답합니다.
`X-SDK-Version`	`header`	`string`	`false`	SDK 버전 정보입니다.
`X-Platform`	`header`	`string`	`false`	클라이언트 플랫폼 정보입니다.
`X-OS-Version`	`header`	`string`	`false`	클라이언트 운영 체제 버전 정보입니다.
`traceparent`	`header`	`string`	`false`	분산 추적을 위한 W3C Trace Context 헤더입니다.
`Accept-Language`	`header`	`string`	`false`	응답 언어 설정입니다.
`User-Agent`	`header`	`string`	`false`	클라이언트 애플리케이션의 User-Agent 정보입니다.
body	body	`ClientCredentialsTokenRequest`	`true`	토큰 발급 요청 정보입니다.

요청 본문 ClientCredentialsTokenRequest

필드	타입	필수	설명
`grantType`	`string`	`true`	토큰 발급 유형입니다. 앱 서버용 토큰을 발급받으므로 `client_credentials`를 지정합니다.
`clientId`	`string`	`true`	프로젝트 설정 > 보안 키에서 확인한 Client ID입니다. 최대 32자입니다.
`clientSecret`	`string`	`true`	프로젝트 설정 > 보안 키에서 확인한 Client Secret입니다. 최대 64자입니다.

호출 예시

curl

curl -X POST 'https://core-api.hiveaxyl.com/token/v1/issue' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-App-Id: {app-id}' \
  -d '{
    "grantType": "client_credentials",
    "clientId": "{client-id}",
    "clientSecret": "{client-secret}"
  }'

응답

공통 data, meta, 오류 본문, 제품 공통 오류 코드는 인증 토큰 응답 및 오류를 참조하세요. 이 섹션에서는 이 API가 실제로 반환하는 객체와 API별 처리 방법을 설명합니다.

성공 응답 data 객체

필드	타입	설명
`data.accessToken`	`string`	발급된 JWT 액세스 토큰입니다. Hive Axyl Server API 요청의 `Authorization` 헤더에 담아 사용합니다.
`data.refreshToken`	`string 또는 null`	JWT 리프레시 토큰입니다. `client_credentials` 방식에서는 항상 `null`입니다.
`data.expiresIn`	`integer`	액세스 토큰이 만료되기까지 남은 시간입니다. 초 단위이며 발급 시점을 기준으로 합니다.

응답 예시

200 OK400 Bad Request

{
  "data": {
    "accessToken": "{access-token}",
    "refreshToken": null,
    "expiresIn": 3600
  },
  "meta": null
}

{
  "type": "/errors/token/invalid-client",
  "title": "Invalid Client",
  "status": 400,
  "detail": "The client credentials are invalid.",
  "instance": "/token/v1/issue",
  "code": "invalid_client",
  "outcome": null
}

API별 처리 시 유의 사항

client_credentials 방식은 리프레시 토큰을 발급하지 않습니다. 액세스 토큰이 만료되면 이 API를 다시 호출해 새 토큰을 받으세요.

발급받은 토큰은 expiresIn 동안 여러 요청에 재사용하세요. API를 호출할 때마다 토큰을 새로 발급하면 불필요한 호출이 늘어납니다.

응답 상태

상태	콘텐츠 유형	의미	응답 헤더	응답 본문 또는 처리
`200`	`application/json`	토큰 발급 성공	-	`data`에 발급된 토큰 정보가 담깁니다.
`400`	`application/problem+json`	요청을 처리할 수 없음	-	-

API별 오류 코드

코드	발생 조건	처리 방법
`invalid_client`	Client ID 또는 Client Secret이 올바르지 않습니다.	프로젝트 설정 > 보안 키에서 두 값을 다시 확인하세요. Client Secret을 교체했다면 앱 서버에 적용한 값도 함께 바꾸세요.
`unsupported_grant_type`	지원하지 않는 `grantType`을 보냈습니다.	`grantType`에 `client_credentials`를 지정했는지 확인하세요.
`app_not_found`	`X-App-Id`의 앱 정보를 찾을 수 없습니다.	프로젝트 설정 > App ID에서 App ID를 다시 확인하세요.

앱 서버용 토큰은 client_credentials 방식으로만 발급받으므로, 다른 grantType에서만 반환되는 invalid_grant 계열 코드는 이 호출에서 발생하지 않습니다.

발급받은 토큰 사용

발급받은 액세스 토큰은 Hive Axyl Server API 요청의 Authorization 헤더에 Bearer {access-token} 형식으로 담습니다. 아래는 Hive Axyl Server API를 호출할 때 함께 보내는 헤더입니다. 요청 본문은 호출할 API의 설명에서 확인하세요.

curl

-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/json' \
-H 'X-App-Id: {app-id}'

사용할 토큰 구분

앱 서버용 토큰은 앱 서버가 자신을 증명하는 값이며, 사용자 개인의 로그인 토큰과는 다릅니다. Hive Axyl Server API마다 Authorization 헤더에 넣는 토큰이 다르므로 아래 목록에서 확인하세요.

액세스 토큰 유효성 확인: 앱 서버용 토큰
사전 인가 키 발급: 앱 서버용 토큰
유저네임 비밀번호 변경: 비밀번호를 바꿀 사용자의 로그인 토큰
소모성 상품 영수증 검증: 앱 서버용 토큰
구독 상품 영수증 검증: 앱 서버용 토큰
구매 내역 조회: 앱 서버용 토큰
리모트 푸시 전송: 앱 서버용 토큰

액세스 토큰 유효성 확인

POST /token/v1/introspect

앱 서버가 앱 클라이언트에서 받은 액세스 토큰이 진짜인지 확인하고, 그 토큰의 주인인 Player ID를 돌려받습니다. 아이템 지급이나 플레이 데이터 저장처럼 위변조를 허용할 수 없는 처리를 하기 전에 호출합니다. 토큰의 유효성을 확인하는 이 방식은 OAuth 2.0 표준인 RFC 7662 Token Introspection을 따릅니다.

위조되었거나 만료되었거나 폐기된 토큰, 액세스 토큰이 아닌 다른 종류의 토큰은 오류가 아니라 data.active가 false인 성공 응답으로 돌아옵니다. HTTP 상태 코드만 보고 판단하지 말고 data.active 값으로 판단하세요.

API 호출 전 준비

호출 주체: 앱 서버
기본 URL: https://core-api.hiveaxyl.com
인증: Authorization: Bearer {access-token}

Warning

인증 헤더에 넣는 액세스 토큰은 토큰 발급으로 받은 앱 서버용 토큰입니다. 검증하려는 사용자의 액세스 토큰은 인증 헤더가 아니라 요청 본문의 token 필드에 넣습니다. 두 값을 바꿔 넣으면 요청이 거부됩니다.

호출 Parameters

이름	위치	타입	필수	설명
`X-App-Id`	`header`	`string`	`true`	Hive 콘솔에 등록한 App ID입니다. 헤더를 보내지 않으면 `missing_field`, 값이 비어 있으면 `missing_app_id`로 응답합니다.
body	body	`IntrospectRequest`	`true`	검증할 토큰을 담는 요청 본문입니다.

요청 본문 IntrospectRequest

필드	타입	필수	설명
`token`	`string`	`true`	검증할 사용자의 액세스 토큰입니다. 앱 클라이언트가 `ISessionManager.AccessToken`에서 읽어 앱 서버로 보낸 값입니다. 최대 4096자이며 민감 정보이므로 로그에 남기지 마세요.

호출 예시

curl

curl -X POST 'https://core-api.hiveaxyl.com/token/v1/introspect' \
  -H 'Authorization: Bearer {master-access-token}' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Id: {app-id}' \
  -d '{
    "token": "{player-access-token}"
  }'

응답

공통 data, meta, 오류 본문, 제품 공통 오류 코드는 인증 토큰 응답 및 오류를 참조하세요. 이 섹션에서는 이 API가 실제로 반환하는 객체와 API별 처리 방법을 설명합니다.

성공 응답 data 객체

필드	타입	설명
`data.active`	`boolean`	토큰 유효 여부입니다. `false`이면 아래 나머지 필드는 응답에 포함되지 않습니다.
`data.playerId`	`integer`	토큰 주인의 Player ID입니다. 앱 서버는 이 값을 사용자 식별 기준으로 사용합니다.
`data.deviceKey`	`string`	토큰이 발급된 기기의 식별자입니다.
`data.expiresAt`	`string`	토큰 만료 시각입니다. ISO 8601 형식입니다.

응답 예시

200 OK 유효한 토큰200 OK 무효한 토큰400 Bad Request

{
  "data": {
    "active": true,
    "playerId": 100000123,
    "deviceKey": "0f8e7d6c5b4a493882716f5e4d3c2b1a",
    "expiresAt": "2026-01-01T00:00:00Z"
  },
  "meta": null
}

{
  "data": {
    "active": false
  },
  "meta": null
}

{
  "type": "/errors/token/introspect-project-mismatch",
  "title": "Introspect Project Mismatch",
  "status": 400,
  "detail": "The target token's project does not match the caller.",
  "instance": "/token/v1/introspect",
  "code": "introspect_project_mismatch",
  "outcome": null
}

API별 처리 시 유의 사항

data.active가 true일 때만 요청을 처리하고, 앱 클라이언트가 함께 보낸 Player ID가 아니라 응답의 data.playerId를 사용자 식별 기준으로 사용하세요. 앱 클라이언트가 보낸 값은 위조될 수 있습니다.

data.active가 false이면 토큰이 위조되었거나 만료되었거나 이미 폐기되었거나, 액세스 토큰이 아닌 다른 종류의 토큰입니다. 앱 서버는 요청을 거부하고, 앱 클라이언트가 다시 로그인해 새 토큰을 받도록 응답하세요.

이 API로는 다른 프로젝트에 속한 토큰을 검증할 수 없습니다. 앱 서버용 토큰과 검증 대상 토큰이 서로 다른 프로젝트에 속하면 introspect_project_mismatch로 거부됩니다.

응답 상태

상태	콘텐츠 유형	의미	응답 헤더	응답 본문 또는 처리
`200`	`application/json`	호출자 인증과 인가를 통과한 정상 응답	-	토큰 유효 여부는 `data.active`로 구분합니다.
`400`	`application/problem+json`	요청을 처리할 수 없음	-	-

API별 오류 코드

코드	발생 조건	처리 방법
`introspect_forbidden`	호출자에게 토큰 유효성 확인 권한이 없습니다.	인증 헤더에 토큰 발급으로 받은 앱 서버용 토큰을 넣었는지, 앱 서버용 토큰과 검증 대상 토큰이 같은 프로젝트에 속하는지 확인하세요.
`introspect_project_mismatch`	검증 대상 토큰이 호출자와 다른 프로젝트에 속합니다.	호출에 사용한 App ID와 앱 서버용 토큰의 프로젝트를 확인하세요.