마인플랫폼 문서

테마

인증 (API 키) ​

공개 API는 API 키로 호출자를 식별해요. 세션 쿠키·비밀번호·OAuth 토큰은 쓰지 않아요.

키 발급 ​

  1. https://mineplatform.kr/dashboard/api 로 이동해요. (로그인 필요)
  2. 키 이름을 1~64자로 입력해요. (예: 디스코드 봇, 상태 모니터)
  3. 발급을 누르면 mp_live_ 로 시작하는 전체 키가 한 번만 표시돼요.
  4. 키를 복사해 비밀번호 관리자·시크릿 스토어 등에 저장해요.

다시 볼 수 없음

전체 키 문자열은 서버에 해시만 저장돼요. 화면을 닫으면 같은 값을 다시 조회할 수 없어요.
분실하면 해당 키를 삭제하고 새로 발급하세요.

키 형식 ​

항목값
접두사mp_live_ (필수)
본문암호학적으로 안전한 난수 (hex)
예시 (가짜)mp_live_a1b2c3d4e5f6… (실제 길이는 더 김)
목록에 보이는 값앞 16자 정도의 prefix만 표시

요청 시 mp_live_ 로 시작하지 않으면 즉시 401 이 납니다.

요청 헤더 ​

http
Authorization: Bearer mp_live_YOUR_FULL_KEY
Accept: application/json
  • 스킴은 Bearer (대소문자 무관) + 공백 + 키 전체입니다.
  • Authorization 헤더가 없거나, Bearer가 아니거나, 키가 비어 있으면 401 입니다.
  • 쿼리 스트링·바디에 키를 넣는 방식은 지원하지 않아요.

잘못된 예 ​

http
# ❌ 쿼리로 전달
GET /v1/servers?api_key=mp_live_...

# ❌ Basic 인증
Authorization: Basic ...

# ❌ Bearer 누락
Authorization: mp_live_...

올바른 예 ​

http
GET /v1/servers HTTP/1.1
Host: api.mineplatform.kr
Authorization: Bearer mp_live_...
Accept: application/json

활성 키 개수 제한 ​

항목제한
사용자당 활성 키최대 5개
삭제(폐기)된 키한도에 포함되지 않음

한도에 도달하면 대시보드에서 기존 키를 삭제한 뒤 새로 발급하세요.

키 삭제 (폐기) ​

대시보드에서 키를 삭제하면 revoked_at이 기록되고, 그 순간부터 해당 키는 401을 받아요.
이미 배포된 봇·스크립트의 환경 변수도 함께 교체해야 해요.

저장·보안 권장 사항 ​

  • 키를 GitHub·Discord 공개 채널·스크린샷에 올리지 마세요.
  • 클라이언트(브라우저·모바일 앱)에 하드코딩하지 말고, 서버 측에서만 호출하세요.
    • CORS는 열려 있지만, 키를 프론트에 넣으면 누구나 탈취할 수 있어요.
  • 유출이 의되면 즉시 폐기하고 새 키를 발급하세요.
  • CI/CD에서는 GitHub Actions Secrets, Cloudflare Secrets 등 시크릿 저장소를 쓰세요.
  • 가능하면 키마다 용도별 이름을 붙여 유출 시 영향을 좁히세요. (예: prod-bot, staging-monitor)

인증 처리 흐름 (참고) ​

  1. Worker가 Authorization에서 Bearer 토큰을 읽어요.
  2. mp_live_ 접두사를 검사해요.
  3. 키 전체의 SHA-256 해시로 DB의 api_keys를 조회해요.
  4. 폐기되지 않았고, 1초 한도를 통과하면 해당 user_id로 요청을 처리해요.
  5. 성공 시 last_used_at이 갱신돼요. (대시보드에서 최근 사용 시각으로 확인 가능)

평문 키는 DB에 저장되지 않아요.

인증 실패 응답 ​

json
{
  "error": "Invalid or missing API key."
}

HTTP 상태: 401 Unauthorized

자세한 오류 형식은 오류·상태 코드를 참고하세요.