인증

JWT (JSON Web Token)는 SDK 요청을 인증하는 권장 방법입니다. 암호화 검증, 자동 토큰 갱신, 사용자별 세션 소유권을 제공합니다.

JWT 서명 키는 Moss 대시보드의 API 키에서 관리합니다.

작동 방식

백엔드에서 JWT 서명 키를 보유합니다 (Moss 대시보드에서 생성)
사용자가 앱을 로드하면 백엔드가 사용자의 신원으로 JWT에 서명합니다
SDK가 모든 요청에 이 토큰을 전송합니다
Moss 백엔드가 서명을 검증하고 사용자 신원을 추출합니다

사용자 앱 로드 → 백엔드에서 JWT 서명 → SDK가 JWT 전송 → Moss에서 검증

설정

1. 서명 키 생성

Moss 대시보드에서 API 키로 이동하여 JWT 서명 키를 생성하세요. 다음을 받게 됩니다:

키 ID (kid) — JWT 헤더에 포함됨
시크릿 — 토큰 서명에 사용 (안전하게 보관하고 클라이언트에 노출하지 마세요)

시크릿은 한 번만 표시됩니다. 백엔드의 환경 변수나 시크릿 관리자에 저장하세요.

2. 토큰 엔드포인트 생성

인증된 사용자를 위해 JWT에 서명하는 엔드포인트를 백엔드에 추가하세요.

Node.js
Python

const jwt = require('jsonwebtoken');

app.get('/api/moss-token', requireAuth, (req, res) => {
  const token = jwt.sign(
    {
      sub: req.user.id,              // 필수: 사용자 식별자
      app: 'YOUR_APPLICATION_ID',    // 필수: Moss 애플리케이션 ID
      email: req.user.email,         // 선택: 사용자 이메일
      name: req.user.name,           // 선택: 사용자 이름
    },
    process.env.MOSS_JWT_SECRET,
    {
      algorithm: 'HS256',
      expiresIn: '1h',
      header: { kid: process.env.MOSS_KEY_ID },
    }
  );

  res.json({ token });
});

import jwt
from datetime import datetime, timedelta

@app.route('/api/moss-token')
@require_auth
def moss_token():
    token = jwt.encode(
        {
            'sub': current_user.id,           # 필수: 사용자 식별자
            'app': 'YOUR_APPLICATION_ID',     # 필수: Moss 애플리케이션 ID
            'email': current_user.email,      # 선택
            'name': current_user.name,        # 선택
            'exp': datetime.utcnow() + timedelta(hours=1),
            'iat': datetime.utcnow(),
        },
        os.environ['MOSS_JWT_SECRET'],
        algorithm='HS256',
        headers={'kid': os.environ['MOSS_KEY_ID']},
    )

    return jsonify({'token': token})

3. SDK 설정

엔드포인트에서 새 토큰을 가져오는 getJwt 함수를 전달하세요. SDK는 토큰이 만료되면 자동으로 이 함수를 호출합니다.

React (NPM)
CDN (스크립트 태그)

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: async () => {
    const res = await fetch('/api/moss-token');
    const data = await res.json();
    return data.token;
  },
}}>
  <AssistantButton />
</AgentProvider>

<script>
  window.mossSettings = {
    apiUrl: 'https://moss-api.viamoss.ai',
    userId: 'USER_ID',
    getJwt: async function() {
      const res = await fetch('/api/moss-token');
      const data = await res.json();
      return data.token;
    },
  };
</script>
<script src="https://cdn.viamoss.ai/moss-sdk@latest.min.js?applicationId=YOUR_APP_ID"></script>

JWT 클레임 참조

클레임	필수	설명
`sub`	예	사용자 식별자 (문자열)
`app`	예	Moss 애플리케이션 UUID
`exp`	예	만료 시간 (Unix 타임스탬프)
`iat`	예	발급 시간 (Unix 타임스탬프)
`email`	아니오	사용자 이메일 주소
`name`	아니오	사용자 표시 이름
`metadata`	아니오	사용자 정의 메타데이터 (객체)

토큰 갱신

getJwt를 제공하면 SDK가 자동으로 토큰 갱신을 처리합니다:

각 요청 전에 토큰 만료를 확인합니다
토큰이 만료 60초 이내이면 getJwt()를 호출합니다
새 토큰으로 실패한 요청을 재시도합니다

갱신이 필요 없는 고정 토큰이 있는 경우 jwt를 대신 사용하세요:

<AgentProvider config={{
  // ...
  jwt: 'YOUR_STATIC_TOKEN',  // 자동 갱신 없음
}}>

프로덕션 애플리케이션에서는 jwt보다 getJwt를 권장합니다. 토큰이 항상 유효한 상태를 보장합니다.

시작하기

SDK

대시보드

설정

보안

가이드

리소스

인증

인증

작동 방식

설정

1. 서명 키 생성

2. 토큰 엔드포인트 생성

3. SDK 설정

JWT 클레임 참조

토큰 갱신

다음 단계

설정

설치

​인증

​작동 방식

​설정

​1. 서명 키 생성

​2. 토큰 엔드포인트 생성

​3. SDK 설정

​JWT 클레임 참조

​토큰 갱신

​다음 단계

설정

설치

인증

작동 방식

설정

1. 서명 키 생성

2. 토큰 엔드포인트 생성

3. SDK 설정

JWT 클레임 참조

토큰 갱신

다음 단계