# 네이버웍스 API 연동 가이드

**[현재 프로젝트 상태]** 네이버웍스 API 연동 미구현 (OAuth2 토큰 관리 로직 없음, 관련 skill 서비스 미존재, auth-server에 Works API 인증 미탑재).

---

## 1. 로빙(RO-BEING) 앱 설정 현황

- **앱 이름**: Ro-being
- **소속**: company-x.partners (155032)

### 1.1. 인증 정보

- **Client ID**: `kFJu_ajl6tb8pBiPEEnS`
- **Client Secret**: `xIz5G0v4wn`
    -   > **⚠️ 경고: 이 값은 외부에 노출되어서는 안 되며, Git 등 버전 관리 시스템에 포함하지 마십시오. Vault 또는 암호화된 환경 변수를 통해 안전하게 관리해야 합니다.**
- **Service Account**: `86rye.serviceaccount@company-x.partners`

### 1.2. 토큰 설정

- **Access Token 유효기간**: 1시간
- **Refresh Token Rotation**: On (보안 강화)

### 1.3. OAuth 설정

- **Redirect URL**: `https://auth.robeing.com/oauth/naverworks/callback`
- **활성화된 Scopes**:
    - `openid`, `profile`, `email` (OIDC 사용자 식별용)
    - `calendar` (캘린더 읽기/쓰기)
    - `contact` (주소록 읽기/쓰기)
    - `file` (드라이브 파일 접근)
    - `mail` (메일 읽기/보내기)
    - `task` (업무 관리)
    - `user` (조직 내 사용자 정보 조회)

---

## 2. 인증 방식

네이버웍스 API를 사용하기 위해서는 먼저 **Access Token**을 발급받아야 합니다. 현재 앱 설정에 따라 아래 두 가지 방식 모두 사용 가능합니다.

1.  **구성원 계정으로 인증 (OAuth 2.0 / OIDC)**: 사용자가 직접 로그인하여 자신의 데이터에 대한 접근을 허용하는 방식입니다. (예: "내 캘린더 일정 조회")
2.  **서비스 계정으로 인증 (JWT)**: 사용자 로그인 없이, 시스템(로빙)이 조직 전체의 데이터에 접근할 때 사용합니다. (예: 주기적인 데이터 동기화)

## 3. API 사용 예시 및 주요 엔드포인트

### 3.1. 캘린더 (Calendar API)

-   **스코프**: `calendar`
-   **주요 엔드포인트**:
    -   `GET /v1.0/users/{userId}/calendar/events`: 특정 사용자의 일정 목록 조회
    -   `POST /v1.0/users/{userId}/calendar/events`: 새 일정 생성
    -   `PUT /v1.0/users/{userId}/calendar/events/{eventId}`: 기존 일정 수정

-   **요청 예시: 새 일정 생성**
    `POST https://www.worksapis.com/v1.0/users/{userId}/calendar/events`
    ```json
    {
      "subject": "Team Meeting",
      "start": {
        "date": "2025-09-18",
        "time": "10:00:00"
      },
      "end": {
        "date": "2025-09-18",
        "time": "11:00:00"
      },
      "attendees": [
        {
          "email": "member1@example.com",
          "isOptional": false
        }
      ]
    }
    ```

### 3.2. 주소록 (Contact API)

-   **스코프**: `contact`, `user`
-   **주요 엔드포인트**:
    -   `GET /v1.0/contacts`: 고객/거래처 연락처 목록 조회
    -   `POST /v1.0/contacts`: 새 연락처 생성
    -   `GET /v1.0/users/{userId}`: 조직 내 사용자 정보 조회

### 3.3. 메일 (Mail API)

-   **스코프**: `mail`
-   **주요 엔드포인트**:
    -   `POST /v1.0/users/{userId}/mail`: 메일 발송
    -   `GET /v1.0/users/{userId}/mail/messages/{messageId}`: 특정 메일 상세 조회

## 4. 로빙 연동 아키텍처

### 4.1. 시크릿 관리 (온프레미스 2서버 환경)

-   **원칙**: 영구 시크릿(Client Secret, Private Key)은 **게이트웨이 서버**에만 중앙 집중식으로 보관합니다.
-   **구현**: 게이트웨이 서버에서 HashiCorp Vault 또는 암호화된 파일 시스템(`600` 권한)을 사용하여 Client ID/Secret을 관리하고, 컨테이너에는 읽기 전용(`:ro`)으로 마운트합니다.
-   **로빙/스킬 서버**: 게이트웨이를 통해 발급된 단기 Access Token만 받아 사용하며, 영구 시크릿을 보관하지 않습니다.

### 4.2. 인증 흐름 및 토큰 관리

-   **JWT 키 관리 (JWKS)**: 게이트웨이는 JWT 서명에 사용하는 공개키 목록을 `/.well-known/jwks.json` 엔드포인트를 통해 노출하여, 다른 서비스들이 토큰을 안전하게 검증하고 키 교체에 대응할 수 있도록 합니다.
-   **토큰 흐름**: 로빙/스킬 서버는 외부 API를 직접 호출하는 대신, 게이트웨이에 API 호출을 위임하고 필요한 단기 토큰을 받아 사용합니다.

## 5. 참고 자료

-   **네이버웍스 개발자 센터 (공식 문서):** [developers.worksmobile.com](https://developers.worksmobile.com)
    -   [인증 가이드](https://developers.worksmobile.com/kr/docs/auth)
    -   [캘린더 API](https://developers.worksmobile.com/kr/document/10070?lang=ko)
    -   [주소록 API](https://developers.worksmobile.com/kr/docs/contact)
    -   [메일 API](https://developers.worksmobile.com/kr/docs/mail)
-   **네이버 개발자 포럼:** API 관련 실제 질의응답을 참고할 수 있습니다.