계정 및 인증 API

'계정 및 인증'에서 앱 서버가 직접 호출하는 Hive Axyl Server API를 설명합니다. 계정 생성, 커스텀 계정 로그인, 커스텀 계정 연동을 앱 서버가 미리 승인하는 grant key 발급 API와, 유저네임 계정의 비밀번호를 바꾸는 API가 있습니다.

사전 인가 키 발급

POST /auth/v1/grant

앱 서버가 앱 클라이언트를 대신해 인증 행위를 미리 승인하는 grant key를 발급받습니다. 앱 서버는 자체 정책으로 요청이 정상인지 판단한 뒤 이 API를 호출합니다. 발급받은 값을 앱 클라이언트에 전달하면, 앱 클라이언트가 계정 생성, 커스텀 계정 로그인, 커스텀 계정 연동 요청에 그 값을 실어 보냅니다.

grant key는 발급 후 60초 동안만 유효한 1회용 값입니다. 실제 인증 요청에 사용되면 즉시 소비되므로 다시 쓸 수 없습니다. 따라서 사용자 입력을 기다리는 시점보다 실제 요청 직전에 발급받으세요.

API 호출 전 준비

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

Warning

인증 헤더에는 토큰 발급으로 받은 앱 서버용 토큰을 넣습니다. 발급된 grant key는 인증 행위를 승인하는 민감 정보이므로 로그나 오류 메시지에 남기지 말고, 앱 클라이언트로 전달할 때는 HTTPS처럼 암호화된 통신을 사용하세요.

호출 Parameters

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

요청 본문 GrantRequest

필드	타입	필수	설명
`authType`	`string`	`true`	승인할 인증 행위 유형입니다. `GUEST_CREATE`, `USERNAME_CREATE`, `CUSTOM_LOGIN`, `CUSTOM_LINK` 중 하나입니다.
`providerId`	`string`	조건부	커스텀 로그인 수단 식별자입니다. `authType`이 `CUSTOM_LOGIN` 또는 `CUSTOM_LINK`이면 `CUSTOM_PROVIDER`를 보냅니다.
`providerUserId`	`string`	조건부	커스텀 로그인 수단이 발급한 사용자 식별자입니다. `authType`이 `CUSTOM_LOGIN` 또는 `CUSTOM_LINK`이면 필수이며 1자 이상 255자 이하입니다.
`targetPlayerId`	`integer`	조건부	커스텀 계정을 연동할 대상 Player ID입니다. `authType`이 `CUSTOM_LINK`이면 필수입니다.

authType별로 함께 보내야 하는 필드와 grant key를 사용하는 곳은 아래와 같습니다.

`authType`	승인 대상	함께 보내는 필드	grant key를 사용하는 곳
`GUEST_CREATE`	게스트 계정 생성	없음	게스트 계정 생성
`USERNAME_CREATE`	유저네임 계정 생성	없음	유저네임 계정 생성
`CUSTOM_LOGIN`	커스텀 계정 로그인	`providerId`, `providerUserId`	커스텀 계정으로 로그인
`CUSTOM_LINK`	커스텀 계정 연동	`providerId`, `providerUserId`, `targetPlayerId`	커스텀 계정 연동

게스트 계정과 유저네임 계정 생성에 grant key가 필요한 경우는 추가 보안 적용을 참조하세요.

호출 예시

curl

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

커스텀 계정을 연동할 때는 아래와 같이 보냅니다.

curl

curl -X POST 'https://core-api.hiveaxyl.com/auth/v1/grant' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Id: {app-id}' \
  -d '{
    "authType": "CUSTOM_LINK",
    "providerId": "CUSTOM_PROVIDER",
    "providerUserId": "{custom-provider-user-id}",
    "targetPlayerId": 20000000234
  }'

응답

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

성공 응답 data 객체

필드	타입	설명
`data.grantKey`	`string`	발급된 grant key입니다. 앱 클라이언트에 전달해 인증 요청에 사용합니다.
`data.createdAt`	`string`	발급 시각입니다. ISO 8601 UTC 형식이며, 이 시각부터 60초 동안만 유효합니다.

응답 예시

200 OK400 Bad Request

{
  "data": {
    "grantKey": "{grant-key}",
    "createdAt": "2026-04-01T09:00:00Z"
  },
  "meta": null
}

{
  "type": "/errors/auth/provider-config-not-found",
  "title": "Provider Config Not Found",
  "status": 400,
  "detail": "No provider configuration exists for this app.",
  "instance": "/auth/v1/grant",
  "code": "provider_config_not_found",
  "outcome": null
}

API별 처리 시 유의 사항

grant key는 발급 시각부터 60초가 지나면 만료됩니다. 앱 서버가 미리 여러 개를 만들어 두거나 캐시하지 말고, 앱 클라이언트가 인증을 요청하는 시점에 하나씩 발급해 전달하세요.

응답 상태

상태	콘텐츠 유형	의미	응답 헤더	응답 본문 또는 처리
`200`	`application/json`	grant key 발급 성공	-	`data.grantKey`를 앱 클라이언트에 전달합니다.
`400`	`application/problem+json`	요청을 처리할 수 없음	-	-

API별 오류 코드

코드	발생 조건	처리 방법
`provider_not_supported`	지원하지 않는 `providerId`를 보냈습니다.	`providerId`에 `CUSTOM_PROVIDER`를 지정했는지 확인하세요.
`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.	Hive 콘솔의 로그인 설정을 확인하세요.

유저네임 비밀번호 변경

PATCH /auth/v1/username/password

유저네임 로그인 수단이 연결된 계정의 비밀번호를 바꿉니다. 유저네임을 어떤 경로로 연동했든 사용할 수 있습니다. 사용자가 앱에서 비밀번호 변경을 요청했을 때, 앱 서버가 본인 확인을 마친 뒤 호출합니다. Hive Axyl 인증 서버는 비밀번호를 바꾸면서 현재 기기를 포함한 모든 기기의 로그인 세션을 폐기합니다. 앱 클라이언트에서 Hive Axyl SDK로 처리하려면 비밀번호 변경을 참조하세요.

API 호출 전 준비

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

Warning

인증 헤더에 넣는 액세스 토큰은 앱 서버용 토큰이 아니라 비밀번호를 바꿀 사용자의 로그인 토큰입니다. 토큰과 비밀번호 해시는 모두 민감 정보이므로 로그나 오류 메시지에 남기지 마세요.

호출 Parameters

이름	위치	타입	필수	설명
`X-App-Id`	`header`	`string`	`true`	Hive 콘솔에 등록한 App ID입니다. 헤더를 보내지 않으면 `missing_field`, 값이 비어 있으면 `missing_app_id`로 응답합니다.
`X-SDK-Version`	`header`	`string`	`false`	SDK 버전입니다. Hive Axyl SDK가 호출할 때 보냅니다.
`X-Platform`	`header`	`string`	`false`	클라이언트 플랫폼 식별자입니다.
`X-OS-Version`	`header`	`string`	`false`	클라이언트 OS 버전입니다.
`traceparent`	`header`	`string`	`false`	W3C Trace Context 값입니다. 분산 추적에 사용합니다.
`Accept-Language`	`header`	`string`	`false`	클라이언트 언어입니다. 다국어 문구 적용에 사용합니다.
`User-Agent`	`header`	`string`	`false`	클라이언트 User-Agent입니다.
body	body	`UsernamePasswordChangeRequest`	`true`	변경할 비밀번호 정보입니다.

요청 본문 UsernamePasswordChangeRequest

필드	타입	필수	설명
`currentPassword`	`string`	`true`	현재 비밀번호입니다. 사용자가 입력한 원본 비밀번호를 `SHA256(raw_password)`로 변환한 64자 16진수 소문자 문자열을 보냅니다.
`newPassword`	`string`	`true`	새 비밀번호입니다. `currentPassword`와 같은 방식으로 변환한 값을 보내며, `currentPassword`와 달라야 합니다.

호출 예시

curl

curl -X PATCH 'https://core-api.hiveaxyl.com/auth/v1/username/password' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-App-Id: {app-id}' \
  -H 'Accept-Language: ko' \
  -d '{
    "currentPassword": "b94f6f125c79e3a5ffaa826f584c10d52ada669e6762051b826b55776d05a8f6",
    "newPassword": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }'

응답

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

성공 응답의 data는 null입니다. 비밀번호 변경 결과 외에 반환하는 값이 없습니다.

응답 예시

200 OK400 Bad Request

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

{
  "type": "/errors/auth/same-password",
  "title": "Same Password",
  "status": 400,
  "detail": "The new password must be different from the current password.",
  "instance": "/auth/v1/username/password",
  "code": "same_password",
  "outcome": null
}

API별 처리 시 유의 사항

비밀번호 변경에 성공하면 Hive Axyl 인증 서버가 현재 기기를 포함한 모든 기기의 로그인 세션을 폐기합니다. 앱 서버는 변경 결과를 앱 클라이언트에 전달해 사용자가 새 비밀번호로 다시 로그인하도록 안내하세요.

token_revoke_failed는 이 계정의 로그인 세션을 폐기하지 못했다는 뜻입니다. 잠시 후 같은 요청을 다시 보내세요.

응답 상태

상태	콘텐츠 유형	의미	응답 헤더	응답 본문 또는 처리
`200`	`application/json`	비밀번호 변경 성공	-	`data`는 `null`입니다.
`400`	`application/problem+json`	요청을 처리할 수 없음	-	-

API별 오류 코드

코드	발생 조건	처리 방법
`same_password`	새 비밀번호가 현재 비밀번호와 같습니다.	다른 비밀번호를 입력하도록 안내하세요.
`username_verify_failed`	현재 비밀번호가 일치하지 않습니다.	현재 비밀번호를 다시 입력하도록 안내하세요.
`username_not_found`	유저네임 계정을 찾을 수 없습니다.	계정 상태를 확인하세요.
`provider_not_exist`	이 계정에 유저네임 로그인 수단이 연결되어 있지 않습니다.	유저네임 연동 여부를 확인하세요.
`token_revoke_failed`	로그인 세션 폐기에 실패했습니다.	잠시 후 같은 요청을 다시 보내세요.
`ip_blocked`	접속 IP가 차단되었습니다.	접속이 제한된 IP라는 사실을 사용자에게 안내하세요.