Modfolio Pay
로그인

인증

Modfolio Pay API는 세 가지 인증 방식을 지원합니다. 사용 시나리오에 맞는 방식을 선택하세요.

Bearer JWT

사용자 대신 API 호출

사용자 컨텍스트

M2M API Key

서버 간 통신

서비스 컨텍스트

Agent API Key

AI 에이전트 인증

에이전트 컨텍스트

Bearer JWT (Connect SSO)

Modfolio Connect SSO로 발급된 JWT 토큰을 Authorization 헤더에 전달합니다. 사용자가 로그인한 상태에서 해당 사용자의 데이터에 접근할 때 사용합니다.

사용 시나리오

  • 프론트엔드에서 사용자의 월렛 잔액 조회
  • 사용자의 구독 정보 확인
  • 사용자의 결제 내역 조회

요청 예시

HTTP
GET /api/v1/wallets HTTP/1.1
Host: my.modfolio.io
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
TypeScript
const pay = createPayClient({
  baseUrl: "https://my.modfolio.io",
  auth: {
    type: "bearer",
    token: session.accessToken,
  },
});
JWT는 Modfolio Connect가 발급합니다. JWKS 엔드포인트를 통해 서명이 자동 검증됩니다. 토큰 만료 시 Connect SDK가 자동으로 갱신합니다.

M2M API Key

서버 간 통신에 사용되는 API Key입니다. X-Api-Key 헤더로 전달하며,X-Source-App 헤더로 호출 앱을 식별합니다. 특정 사용자의 데이터에 접근할 때는 X-User-Id 헤더를 추가합니다.

사용 시나리오

  • 백엔드에서 사용자의 구독 상태 확인
  • 서버 사이드에서 크레딧 차감
  • 배치 작업에서 결제 상태 동기화

요청 예시

HTTP
POST /api/v1/wallets/charge-action HTTP/1.1
Host: my.modfolio.io
X-Api-Key: mpsk_live_abc123...
X-Source-App: gistcore
X-User-Id: user_abc123
Content-Type: application/json

{
  "actionCode": "ai_generation",
  "idempotencyKey": "req_unique_001"
}
TypeScript
const pay = createPayClient({
  baseUrl: "https://my.modfolio.io",
  auth: {
    type: "api-key",
    key: process.env.MODFOLIO_PAY_KEY,
    sourceApp: "gistcore",
    userId: "user_abc123",
  },
});
API Key는 서버 사이드에서만 사용하세요. 클라이언트 코드에 노출하면 보안 위험이 발생합니다. 환경 변수로 관리하고 절대 소스 코드에 하드코딩하지 마세요.

Agent API Key (mpak_)

AI 에이전트 전용 인증 키입니다. 스코프 기반 권한 모델과 지출 한도를 지원하여, 에이전트가 허용된 범위 내에서만 API를 호출할 수 있도록 합니다.

특징

  • 스코프 기반 권한 — 읽기/쓰기 권한을 리소스별로 세분화
  • 지출 한도 — 일간/월간 최대 지출 금액 설정
  • 감사 로그 — 모든 에이전트 호출이 감사 이벤트로 기록
  • 즉시 비활성화 — 이상 활동 감지 시 키를 즉시 비활성화 가능

요청 예시

HTTP
GET /api/v1/wallets HTTP/1.1
Host: my.modfolio.io
Authorization: Bearer mpak_live_agent_xyz789...
X-Source-App: gistcore
TypeScript
const pay = createPayClient({
  baseUrl: "https://my.modfolio.io",
  auth: {
    type: "agent-key",
    key: process.env.MODFOLIO_AGENT_KEY,
    sourceApp: "gistcore",
  },
});

인증 방식 비교

Bearer JWTM2M API KeyAgent Key
헤더Authorization: BearerX-Api-KeyAuthorization: Bearer
접두사eyJ... (JWT)mpsk_mpak_
만료1시간 (자동 갱신)영구 (수동 폐기)영구 (수동 폐기)
사용자 컨텍스트자동 (JWT claim)X-User-Id 헤더스코프 기반
지출 한도해당 없음해당 없음지원