> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증

> JWT 인증으로 SDK 통합 보호하기

# 인증

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

<Info>
  JWT 서명 키는 [Moss 대시보드](https://dashboard.viamoss.ai)의 **API 키**에서 관리합니다.
</Info>

## 작동 방식

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

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

## 설정

### 1. 서명 키 생성

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

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

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

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

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

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    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 });
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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})
    ```
  </Tab>
</Tabs>

### 3. SDK 설정

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

<Tabs>
  <Tab title="React (NPM)">
    ```tsx theme={null}
    <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>
    ```
  </Tab>

  <Tab title="CDN (스크립트 태그)">
    ```html theme={null}
    <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>
    ```
  </Tab>
</Tabs>

## JWT 클레임 참조

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

## 토큰 갱신

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

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

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

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

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

## 다음 단계

<CardGroup cols={2}>
  <Card title="설정" icon="gear" href="/ko/sdk/configuration">
    전체 SDK 설정 참조
  </Card>

  <Card title="설치" icon="download" href="/ko/sdk/installation">
    프레임워크별 설치 가이드
  </Card>
</CardGroup>