← 문서

OAuth2 + 설치 URL

GameVox의 OAuth2 흐름은 Discord와 와이어 수준에서 호환됩니다. 인가 URL, 토큰 교환, 스코프 이름, 그랜트 유형이 모두 일치합니다. 이 페이지에서는 설치 링크의 동작과 확인 화면의 표시를 좌우하는 몇 가지 필드를 다룹니다.

엔드포인트

GET  https://gamevox.com/oauth2/authorize
POST https://api.gamevox.com/oauth2/token
POST https://api.gamevox.com/oauth2/token/revoke
GET  https://api.gamevox.com/oauth2/@me

클라이언트 자격 증명

모든 애플리케이션에는 클라이언트 ID(애플리케이션 Snowflake)와 클라이언트 시크릿이 발급됩니다. 시크릿은 앱 생성 시 한 번, 그리고 교체 시 한 번만 표시되며, 저장되는 것은 bcrypt 해시와 접두사·마지막 4자뿐입니다.

• 교체: POST /developer-portal/applications/{id}/reset-secret. 이전 시크릿은 즉시 무효화됩니다.
• 퍼블릭 클라이언트(모바일 앱, SPA): 퍼블릭 클라이언트를 켜세요. 토큰 엔드포인트가 시크릿 없이 PKCE를 받아들입니다. 퍼블릭 클라이언트에 발급된 토큰은 client_credentials 그랜트를 사용할 수 없습니다.

설치 컨텍스트

설치 탭에 있는, 서로 독립적인 두 개의 체크박스입니다.

• 사용자 설치: 봇이 호출한 사용자의 계정에 설치되며, 그 사용자가 있는 어떤 채널에서도 명령어를 쓸 수 있습니다.
• 서버 설치: 봇이 서버에 설치되며, 명령어는 그 서버에서만 사용할 수 있습니다.

최소한 하나는 켜야 합니다. 확인 화면은 켜진 항목에 따라 달라져, 둘 다 켜져 있으면 사용자가 고르고, 하나만 켜져 있으면 선택기가 표시되지 않습니다.

와이어 포맷 참고: “서버 설치”의 컬럼 이름은 Discord와 바이트 단위로 같게 유지하기 위해 install_guild_install입니다. 포털 UI에서 “서버”라고 부르는 것은 GameVox가 길드가 아니라 서버라고 부르기 때문입니다.

기본 설치 설정

켜 둔 각 컨텍스트마다, 확인 화면에서 미리 선택될 스코프와(서버 설치의 경우) 권한 비트필드를 설정합니다. 사용자는 확인 화면에서 스코프를 더 좁힐 수 있습니다.

• 스코프: 컨텍스트당 최대 25개. 사용 가능한 문자는 [a-z0-9._-]. 중복은 조용히 제거됩니다.
• 권한(서버 설치만): 10진수 문자열, 최대 32자. Discord의 권한 정수와 같습니다.

자주 쓰는 기본값:

User install   → ["applications.commands"]
Server install → ["bot", "applications.commands"], perms="0"

설치 링크 모드

드롭다운으로 디렉터리 등록의 설치 버튼이 어떻게 동작할지 정합니다.

• 없음: 설치 버튼을 표시하지 않습니다. 설치는 직접 별도로 처리합니다.
• GameVox 제공: 기본 설치 설정으로 URL을 생성합니다. 실제 URL은 포털 아래에 표시됩니다.
• 사용자 지정 URL: 완전한 https:// URL을 지정합니다(사용자별 state를 발급하는 자체 설치 게이트웨이 등).

GameVox 제공 URL의 형태

https://gamevox.com/oauth2/authorize
  ?client_id={application.id}
  &permissions={perms}
  &scope={URL 인코딩 후 공백으로 이은 스코프}
  &integration_type={0=서버, 1=사용자}
  &response_type=code

두 컨텍스트가 모두 켜져 있으면 링크에서 integration_type이 빠지고, 확인 화면에 선택기가 표시됩니다.

공개 키와 HTTP 모드 인터랙션

모든 앱에 32바이트 Ed25519 공개 키가 발급되며, 일반 정보 탭에 읽기 전용으로 표시됩니다. 애플리케이션 설정에서 인터랙션 엔드포인트 URL을 지정하면, GameVox가 대응하는 개인 키로 서명한 인터랙션 페이로드를 그 주소로 POST합니다. 공개 키를 자동으로 불러오는 라이브러리(discord-interactions 등)는 추가 설정 없이 서명을 검증합니다.

• 엔드포인트가 설정되어 있고 2xx를 반환하면 인터랙션은 HTTP로만 전달되며, 게이트웨이로는 아무것도 가지 않습니다.
• 엔드포인트에 도달할 수 없거나 2xx가 아닌 응답을 주면, GameVox는 봇의 게이트웨이 세션으로 인터랙션을 전달하는 방식으로 되돌아갑니다.
• 서명 방식, 헤더 이름, PING 확인 응답이 Discord와 바이트 단위로 같습니다.
• 자체 호스팅 서버는 아직 인터랙션을 전달하지 않습니다. 현재 HTTP 모드 전달은 클라우드 길드의 인터랙션에서만 동작합니다.

스코프(현재 지원)

스코프	효과
identify	사용자의 id, 사용자 이름, 아바타를 읽습니다.
email	사용자의 인증된 기본 이메일을 읽습니다.
guilds	사용자의 서버 목록(id, 이름, 아이콘, 소유자 표시, 권한)을 읽습니다.
guilds.join	PUT /guilds/{id}/members/{user_id}로 사용자를 서버에 참여시킵니다.
bot	서버에 봇 사용자를 추가하는 서버 설치에 필요합니다.
applications.commands	설치 범위 안에서 슬래시 / 사용자 / 메시지 명령어를 등록할 수 있게 합니다.
messages.read	예약됨. 현재는 와이어에서 거부됩니다.

Discord와의 차이

• Premium Apps와 엔타이틀먼트는 없습니다. 명령어 권한 엔드포인트로 제공하는 것은 applications.commands.permissions.update뿐입니다.
• 토큰에 “팀 관리” 개념은 없습니다. 팀 소유 앱이라도 OAuth 토큰은 애플리케이션에 속하며 특정 팀 구성원에게 속하지 않습니다.
• 앱 테스터(팀 탭)는 비공개 앱의 확인 화면에서 공개/비공개 제한을 우회합니다. 테스터 목록에 있는 사용자는 비공개 앱을 설치할 수 있고, 그 외에는 “찾을 수 없음” 페이지를 보게 됩니다.

← 문서로 돌아가기