Bot-Hosting
로그인 무료로 시작

OAuth 2.1

다른 앱에서 Bot-Hosting 계정으로 사용자가 로그인하게 하세요. "Discord로 로그인"과 같은 방식이에요. OAuth 2.1과 PKCE 기반이라 표준 OAuth 클라이언트면 모두 쓸 수 있어요.

내 계정을 직접 제어할 때는 API 키를 쓰세요. 다른 사람의 계정에서 동작하는 앱을 만든다면 OAuth를 쓰세요. 키를 붙여넣는 대신 사용자가 로그인하고 동의해요. ChatGPT 같은 AI 어시스턴트도 바로 이 흐름으로 연결돼요.

진행 흐름

  1. 01 앱 만들기 개발자 설정에서 이름과 리다이렉트 URI를 등록하세요. 시크릿 없는 공개 client_id를 받아요.
  2. 02 사용자를 승인 화면으로 보내기 PKCE와 함께 /oauth/authorize로 리다이렉트하세요. 사용자가 로그인하고 범위를 승인해요.
  3. 03 코드 교환 사용자가 코드를 가지고 돌아와요. 이 코드를 토큰 엔드포인트에 POST해서 액세스 토큰을 받으세요.
  4. 04 사용자 권한으로 API 호출 토큰을 Bearer로 /api/v1에 보내고, 백그라운드에서 갱신하세요.

엔드포인트

엔드포인트용도
GET /oauth/authorize브라우저에서 열리는 사용자 동의 화면.
POST /api/oauth/token코드를 토큰으로 교환하거나 토큰을 갱신해요.
POST /api/oauth/register동적 클라이언트 등록(RFC 7591), 선택 사항.
GET /.well-known/oauth-authorization-server디스커버리 메타데이터.
GET /.well-known/oauth-protected-resourceMCP 클라이언트가 쓰는 리소스 메타데이터.

토큰 유효 기간

인가 코드 10분 일회용이며 PKCE와 연결돼요.
액세스 토큰 7일 /api/v1 호출용 Bearer예요.
리프레시 토큰 30일 사용할 때마다 교체돼요.

갱신

갱신할 때마다 새 리프레시 토큰을 반환하고 이전 토큰은 폐기돼요. 저장된 토큰을 항상 덮어쓰세요. 갱신 결과가 invalid_grant이면 사용자를 1단계부터 다시 진행시키세요.

보안

  • 토큰은 사용자와 연결해 서버 쪽에 저장하세요. 브라우저나 공개 리포지토리에는 절대 내보내지 마세요.
  • 사용자가 앱 연결을 해제하는 즉시 토큰이 폐기돼요.
  • 운영 환경에서는 https 리다이렉트 URI를 쓰세요. 로컬 테스트에서는 http도 허용돼요.
  • 승인된 범위와 상관없이 OAuth 토큰에는 관리자 권한이 부여되지 않아요.