인증 가이드

멜로밍 OpenAPI의 인증 방법과 보안 모범 사례를 안내합니다.

인증 개요

멜로밍 OpenAPI는 두 가지 인증 방식을 지원합니다.

방식	설명	권장 사용
API Key	애플리케이션 식별 및 사용량 관리	읽기 API에 선택적으로 사용
OAuth 2.0	사용자 권한 기반 토큰 인증	채널/콘텐츠 관리 API

읽기 전용 API는 인증이 필요 없습니다

GET /v1/** 요청은 인증 없이 호출할 수 있습니다. POST, PATCH, DELETE 요청은 인증이 필요하며, 채널/콘텐츠 관리 API는 OAuth 2.0 Access Token이 필수입니다.

API Key 인증

API Key는 애플리케이션 식별과 사용량(쿼터) 추적을 위해 사용할 수 있습니다.

API Key 발급받기

개발자 센터 로그인

멜로밍 계정으로 로그인합니다.

애플리케이션 등록

애플리케이션 등록을 클릭하여 새 앱을 생성합니다.

앱 정보 입력

앱 이름, 설명, Redirect URI 등을 입력하고 제출합니다.

API Key 발급

승인 후 API Key가 발급됩니다.

애플리케이션 등록하기 →

API Key 형식

API Key는 환경에 따라 다른 접두사를 가집니다.

환경	접두사	예시
Live	`mlm_live_`	`mlm_live_a1b2c3d4e5f6...`
Test	`mlm_test_`	`mlm_test_x9y8z7w6v5...`

API Key 사용하기

두 가지 방법으로 API Key를 전달할 수 있습니다.

X-API-Key 헤더


curl https://openapi.meloming.com/v1/channels/1 \
  -H "X-API-Key: mlm_live_your_api_key"

채널/콘텐츠 관리 API는 OAuth Access Token이 필요하며, API Key는 선택적으로 함께 보낼 수 있습니다.

코드 예시

JavaScript


const response = await fetch('https://openapi.meloming.com/v1/channels/1', {
  headers: {
    'X-API-Key': 'mlm_live_your_api_key',
  },
});
 
const data = await response.json();

OAuth 2.0

사용자를 대신하여 API를 호출해야 하는 경우 OAuth 2.0을 사용합니다.

지원하는 Grant Types

Grant Type	용도	사용자 동의
`client_credentials`	애플리케이션 자체 인증 (M2M)	불필요
`authorization_code`	사용자 대신 API 호출	필요
`refresh_token`	Access Token 갱신	불필요

/oauth/token은 application/x-www-form-urlencoded와 application/json 요청을 모두 지원합니다.

Client Credentials Flow

서버 간 통신에서 애플리케이션 자체를 인증할 때 사용합니다.

1. Access Token 발급


curl -X POST https://openapi.meloming.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=read"

응답


{
  "access_token": "eyJhbGciOiJIUzM4NCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

2. API 호출


curl https://openapi.meloming.com/v1/channels/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzM4NCJ9..."

Authorization Code Flow

사용자 동의를 받아 사용자 대신 API를 호출할 때 사용합니다.

1. 인증 요청

사용자를 다음 URL로 리다이렉트합니다:


https://openapi.meloming.com/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=read%20write&
  state=RANDOM_STATE&
  code_challenge=YOUR_CODE_CHALLENGE&
  code_challenge_method=S256

code_challenge_method는 S256 또는 plain을 지원합니다. (PKCE 선택)

2. Authorization Code 수신

사용자가 동의하면 redirect_uri로 code가 전달됩니다:


YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=RANDOM_STATE

3. Access Token 교환


curl -X POST https://openapi.meloming.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Token 갱신

Access Token이 만료되면 Refresh Token으로 갱신합니다:


curl -X POST https://openapi.meloming.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Token 폐기


curl -X POST https://openapi.meloming.com/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_ACCESS_OR_REFRESH_TOKEN", "token_type_hint": "access_token"}'

Token 정보 조회


curl -X POST https://openapi.meloming.com/oauth/introspect \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_ACCESS_TOKEN", "token_type_hint": "access_token"}'

Token 유효 기간

토큰	유효 기간
Access Token	1시간
Refresh Token	7일

보안 모범 사례

권장 사항

API Key는 환경 변수나 비밀 관리 서비스에 저장
HTTPS만 사용하여 API 호출
API Key 권한을 최소한으로 설정
사용하지 않는 API Key는 즉시 삭제
정기적으로 API Key 로테이션
클라이언트 측 코드에 API Key 노출 금지

금지 사항

다음 행위는 절대 금지됩니다:

API Key를 소스 코드에 하드코딩
API Key를 클라이언트(브라우저, 앱)에 노출
API Key를 공개 저장소에 커밋
API Key를 로그에 기록
API Key를 URL 파라미터로 전달
타인과 API Key 공유

인증 에러 처리

HTTP 상태	에러 코드	설명	해결 방법
`401`	AUTHENTICATION_REQUIRED	인증 정보 누락 또는 유효하지 않음	OAuth 토큰 또는 API Key 확인
`401`	INVALID_API_KEY	API Key가 유효하지 않음	API Key 확인
`401`	invalid_client	OAuth client 인증 실패	client_id/secret 확인
`400`	invalid_grant	OAuth grant 오류	code/refresh_token 확인
`400`	unsupported_grant_type	grant_type 미지원	지원되는 grant_type 사용
`403`	PERMISSION_DENIED	리소스 권한 부족	채널 권한 확인

멜로밍Developers