사용자 닉네임 목록 조회 API

파트너사가 카카오 서버로 호출하는 API입니다.
전달한 회원번호(user_ids) 목록에 대해 각 사용자의 게임플레이 프로필 닉네임을 일괄 조회합니다.

게임 안에서 사용자 표기·랭킹에 카카오톡 게임플레이 닉네임을 그대로 사용할 때 씁니다.

Endpoint

http

GET https://kapi.kakao.com/v1/gameplay/profiles

요구 사항

카카오 로그인 사용 설정

인증

파트너사 디벨로퍼스 앱의 어드민 키로 인증합니다.

Header	설명
`Authorization`	필수`KakaoAK {SERVICE_APP_ADMIN_KEY}`: 인증 방식, 서비스 앱 어드민 키로 인증 요청
`Content-Type`	필수`application/x-www-form-urlencoded;charset=utf-8`

주의사항

어드민 키는 앱의 모든 권한을 가지므로 어떤 경우에도 외부에 노출되면 안 됩니다.
게임 클라이언트 번들·소스 저장소·로그에 키를 남기지 말고, 파트너사 서버의 환경 변수나 시크릿 저장소에서 주입합니다.
게임웹뷰에서 이 API를 직접 호출하면 요청 헤더에 키가 그대로 드러나므로, 반드시 파트너사 서버를 경유해 호출합니다.

Request

조회할 회원번호를 쿼리 파라미터로 전달합니다.

파라미터	타입	설명
`user_ids`	`Long[]`	필수게임플레이 프로필을 조회할 사용자의 회원번호 목록. 회원번호는 카카오계정과 앱이 연결될 때 부여하는 앱별 사용자 ID입니다. 최대 50개이며, 초과하면 여러 번 나누어 호출합니다.

bash

curl -G GET "https://kapi.kakao.com/v1/gameplay/profiles" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  --data-urlencode 'user_ids=[123456789,987654321]'

Response

200 OK.

필드	타입	제공 여부	설명
`targets`	`GameplayProfileInfo[]`	항상	조회된 게임플레이 프로필 목록. 조회된 프로필이 없으면 빈 배열

GameplayProfileInfo

필드	타입	제공 여부	설명
`user_id`	`Long`	항상	서비스 앱의 회원번호
`nickname`	`String`	항상	게임플레이 프로필 닉네임

조회된 프로필이 있는 경우

json

{
  "targets": [
    {
      "user_id": 123456789,
      "nickname": "카카오프렌즈"
    },
    {
      "user_id": 987654321,
      "nickname": "게임마스터"
    }
  ]
}

조회된 프로필이 없는 경우

json

{
  "targets": []
}

주의사항

조회할 수 없는 사용자는 응답에서 제외됩니다.
따라서 요청한 회원번호 개수와 targets 길이가 다를 수 있고, 하나도 조회되지 않으면 빈 배열이 옵니다.
응답을 요청 목록의 인덱스(순번)와 1:1로 가정하면 어긋납니다.
결과를 매칭할 때는 순번이 아니라 각 항목의 user_id 값을 키로 매핑해야 합니다.
닉네임을 얻지 못한 사용자를 위해 게임 자체의 대체 표기(예: user138531)를 준비해 두는 것을 권장합니다.

에러

응답 코드와 에러 코드는 카카오 API 공통 규격을 따릅니다.
상세는 에러 코드를 참고하세요.

참고 문서

게임플레이 파트너센터오픈 예정: 게임 정보 관리
액션데이터 API: 사용자별 실제 랭킹 기록값 전송
카카오싱크 설정: 회원번호 확보를 위한 인증·동의 설정
기술 문의: 카카오디벨로퍼스 데브톡

사용자 닉네임 목록 조회 API ​

Endpoint ​

요구 사항 ​

인증 ​

Request ​

Response ​

에러 ​

참고 문서 ​