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

# 인증 (Authentication)

> SMS, 이메일, OTP 기반 인증 API

## 개요

User 서비스의 인증 도메인은 다양한 인증 방식을 제공합니다. SMS 인증, 이메일 인증, OTP(일회용 비밀번호), 익명 로그인, 서드파티 토큰 관리 등을 지원합니다.

## Queries

### refreshToken

리프레시 토큰을 사용하여 새로운 액세스 토큰을 발급받습니다.

#### GraphQL Signature

```graphql theme={null}
query RefreshToken($refreshToken: String!) {
  refreshToken(refreshToken: $refreshToken) {
    accessToken
    refreshToken
  }
}
```

#### 파라미터

<ParamField path="refreshToken" type="String!" required>
  기존 리프레시 토큰
</ParamField>

#### 응답

<ResponseField name="accessToken" type="String!">
  새로 발급된 액세스 토큰
</ResponseField>

<ResponseField name="refreshToken" type="String!">
  새로 발급된 리프레시 토큰
</ResponseField>

#### 예제

<CodeGroup>
  ```graphql Request theme={null}
  query {
    refreshToken(refreshToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...") {
      accessToken
      refreshToken
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "refreshToken": {
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
  ```
</CodeGroup>

***

### thirdParties

등록된 모든 서드파티 사용자 목록을 조회합니다.

#### GraphQL Signature

```graphql theme={null}
query ThirdParties {
  thirdParties {
    id
    name
    authority
    trustedHosts
  }
}
```

#### 응답

<ResponseField name="id" type="ID!">
  서드파티 사용자 ID
</ResponseField>

<ResponseField name="name" type="String!">
  서드파티 이름
</ResponseField>

<ResponseField name="authority" type="Int">
  권한 레벨
</ResponseField>

<ResponseField name="trustedHosts" type="String">
  신뢰할 수 있는 호스트 목록
</ResponseField>

***

## Mutations

### requestAnonymousSignIn

익명 로그인 요청을 생성하고 인증 토큰을 발급합니다.

#### GraphQL Signature

```graphql theme={null}
mutation RequestAnonymousSignIn($type: String) {
  requestAnonymousSignIn(type: $type) {
    authId
    token
  }
}
```

#### 파라미터

<ParamField path="type" type="String">
  익명 로그인 타입 (선택사항)
</ParamField>

#### 응답

<ResponseField name="authId" type="ID!">
  인증 ID
</ResponseField>

<ResponseField name="token" type="String!">
  익명 로그인 토큰
</ResponseField>

#### 예제

<CodeGroup>
  ```graphql Request theme={null}
  mutation {
    requestAnonymousSignIn(type: "kiosk") {
      authId
      token
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "requestAnonymousSignIn": {
        "authId": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
        "token": "anon_token_xyz123"
      }
    }
  }
  ```
</CodeGroup>

***

### waitAnonymousSignIn

익명 로그인 승인을 대기합니다.

#### GraphQL Signature

```graphql theme={null}
mutation WaitAnonymousSignIn($token: String!, $authId: ID!) {
  waitAnonymousSignIn(token: $token, authId: $authId)
}
```

#### 파라미터

<ParamField path="token" type="String!" required>
  익명 로그인 토큰
</ParamField>

<ParamField path="authId" type="ID!" required>
  인증 ID
</ParamField>

#### 응답

<ResponseField name="result" type="String">
  로그인 결과 문자열
</ResponseField>

***

### anonymousSignIn

익명 로그인을 승인합니다.

#### GraphQL Signature

```graphql theme={null}
mutation AnonymousSignIn($token: String!) {
  anonymousSignIn(token: $token) {
    success
    error
  }
}
```

#### 파라미터

<ParamField path="token" type="String!" required>
  익명 로그인 토큰
</ParamField>

#### 응답

<ResponseField name="success" type="Boolean">
  성공 여부
</ResponseField>

<ResponseField name="error" type="String">
  에러 메시지 (실패 시)
</ResponseField>

***

### requestSMSAuth

휴대폰 번호로 SMS 인증번호를 발송합니다.

#### GraphQL Signature

```graphql theme={null}
mutation RequestSMSAuth($phone: String!) {
  requestSMSAuth(phone: $phone) {
    success
    error
  }
}
```

#### 파라미터

<ParamField path="phone" type="String!" required>
  인증번호를 받을 휴대폰 번호
</ParamField>

#### 응답

<ResponseField name="success" type="Boolean">
  SMS 발송 성공 여부
</ResponseField>

<ResponseField name="error" type="String">
  에러 메시지 (실패 시)
</ResponseField>

#### 예제

<CodeGroup>
  ```graphql Request theme={null}
  mutation {
    requestSMSAuth(phone: "01012345678") {
      success
      error
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "requestSMSAuth": {
        "success": true,
        "error": null
      }
    }
  }
  ```
</CodeGroup>

***

### confirmSMSAuth

SMS로 받은 인증번호를 검증하고 인증 해시를 발급합니다.

#### GraphQL Signature

```graphql theme={null}
mutation ConfirmSMSAuth($phone: String!, $number: String!) {
  confirmSMSAuth(phone: $phone, number: $number)
}
```

#### 파라미터

<ParamField path="phone" type="String!" required>
  인증번호를 받은 휴대폰 번호
</ParamField>

<ParamField path="number" type="String!" required>
  SMS로 받은 인증번호
</ParamField>

#### 응답

<ResponseField name="authHash" type="String!">
  인증 해시 (회원가입 또는 비밀번호 변경 시 사용)
</ResponseField>

#### 예제

<CodeGroup>
  ```graphql Request theme={null}
  mutation {
    confirmSMSAuth(
      phone: "01012345678"
      number: "123456"
    )
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "confirmSMSAuth": "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    }
  }
  ```
</CodeGroup>

***

### verifyEmail

이메일 인증을 확인합니다.

#### GraphQL Signature

```graphql theme={null}
mutation VerifyEmail($email: String!, $authHash: String!) {
  verifyEmail(email: $email, authHash: $authHash) {
    success
    error
  }
}
```

#### 파라미터

<ParamField path="email" type="String!" required>
  인증할 이메일 주소
</ParamField>

<ParamField path="authHash" type="String!" required>
  이메일로 받은 인증 해시
</ParamField>

#### 응답

<ResponseField name="success" type="Boolean">
  이메일 인증 성공 여부
</ResponseField>

<ResponseField name="error" type="String">
  에러 메시지 (실패 시)
</ResponseField>

***

### requestEmailVerification

로그인한 사용자의 이메일로 인증 메일을 발송합니다.

#### GraphQL Signature

```graphql theme={null}
mutation RequestEmailVerification {
  requestEmailVerification
}
```

#### 응답

<ResponseField name="result" type="Boolean">
  이메일 발송 성공 여부
</ResponseField>

<Info>
  이 API는 인증이 필요하며, 로그인한 사용자의 이메일로 자동 발송됩니다.
</Info>

***

### revokeToken

현재 사용 중인 토큰을 폐기하고 새 토큰을 발급합니다.

#### GraphQL Signature

```graphql theme={null}
mutation RevokeToken {
  revokeToken {
    accessToken
    refreshToken
  }
}
```

#### 응답

<ResponseField name="accessToken" type="String!">
  새로 발급된 액세스 토큰
</ResponseField>

<ResponseField name="refreshToken" type="String!">
  새로 발급된 리프레시 토큰
</ResponseField>

***

### setOtpKey

OTP(일회용 비밀번호) 키를 생성합니다.

#### GraphQL Signature

```graphql theme={null}
mutation SetOtpKey {
  setOtpKey {
    otpKey
    qrCode
  }
}
```

#### 응답

<ResponseField name="otpKey" type="String!">
  OTP 시크릿 키
</ResponseField>

<ResponseField name="qrCode" type="String!">
  QR 코드 이미지 (Base64 또는 URL)
</ResponseField>

#### 예제

<CodeGroup>
  ```graphql Request theme={null}
  mutation {
    setOtpKey {
      otpKey
      qrCode
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "setOtpKey": {
        "otpKey": "JBSWY3DPEHPK3PXP",
        "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
      }
    }
  }
  ```
</CodeGroup>

<Info>
  QR 코드를 Google Authenticator 또는 다른 OTP 앱으로 스캔하여 등록하세요.
</Info>

***

### lockOtpKey

OTP 키를 검증하고 활성화합니다.

#### GraphQL Signature

```graphql theme={null}
mutation LockOtpKey($input: LockOtpInput!) {
  lockOtpKey(input: $input) {
    success
  }
}
```

#### 파라미터

<ParamField path="input.otp" type="String!" required>
  OTP 앱에서 생성된 6자리 코드
</ParamField>

#### 응답

<ResponseField name="success" type="Boolean!">
  OTP 활성화 성공 여부
</ResponseField>

#### 예제

<CodeGroup>
  ```graphql Request theme={null}
  mutation {
    lockOtpKey(input: { otp: "123456" }) {
      success
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "lockOtpKey": {
        "success": true
      }
    }
  }
  ```
</CodeGroup>

***

### getThirdPartyToken

서드파티 시스템용 토큰을 발급받습니다.

#### GraphQL Signature

```graphql theme={null}
mutation GetThirdPartyToken($name: String!) {
  getThirdPartyToken(name: $name)
}
```

#### 파라미터

<ParamField path="name" type="String!" required>
  서드파티 시스템 이름
</ParamField>

#### 응답

<ResponseField name="token" type="String">
  서드파티 토큰
</ResponseField>

***

### registerThirdParty

새로운 서드파티 사용자를 등록합니다.

#### GraphQL Signature

```graphql theme={null}
mutation RegisterThirdParty($input: ThirdPartyInput!) {
  registerThirdParty(input: $input) {
    id
    name
    authority
    trustedHosts
  }
}
```

#### 파라미터

<ParamField path="input.name" type="String!" required>
  서드파티 이름
</ParamField>

<ParamField path="input.authorities" type="[String!]!" required>
  권한 목록
</ParamField>

<ParamField path="input.trustedHosts" type="String">
  신뢰할 수 있는 호스트 (선택사항)
</ParamField>

#### 응답

<ResponseField name="id" type="ID!">
  생성된 서드파티 사용자 ID
</ResponseField>

<ResponseField name="name" type="String!">
  서드파티 이름
</ResponseField>

<ResponseField name="authority" type="Int">
  권한 레벨
</ResponseField>

<ResponseField name="trustedHosts" type="String">
  신뢰할 수 있는 호스트
</ResponseField>

***

### updateThirdParty

기존 서드파티 사용자 정보를 수정합니다.

#### GraphQL Signature

```graphql theme={null}
mutation UpdateThirdParty($input: UpdateThirdPartyInput!) {
  updateThirdParty(input: $input) {
    id
    name
    authority
    trustedHosts
  }
}
```

#### 파라미터

<ParamField path="input.id" type="ID!" required>
  수정할 서드파티 사용자 ID
</ParamField>

<ParamField path="input.name" type="String">
  새로운 이름 (선택사항)
</ParamField>

<ParamField path="input.authorities" type="[String!]">
  새로운 권한 목록 (선택사항)
</ParamField>

<ParamField path="input.trustedHosts" type="String">
  새로운 신뢰 호스트 (선택사항)
</ParamField>

***

### modifyThirdPartyAccessOnAccommodation

특정 숙박 시설에 대한 서드파티 접근 권한을 설정합니다.

#### GraphQL Signature

```graphql theme={null}
mutation ModifyThirdPartyAccessOnAccommodation(
  $accommodationId: ID!
  $thirdParty: String!
  $allow: Boolean!
) {
  modifyThirdPartyAccessOnAccommodation(
    accommodationId: $accommodationId
    thirdParty: $thirdParty
    allow: $allow
  )
}
```

#### 파라미터

<ParamField path="accommodationId" type="ID!" required>
  숙박 시설 ID
</ParamField>

<ParamField path="thirdParty" type="String!" required>
  서드파티 이름
</ParamField>

<ParamField path="allow" type="Boolean!" required>
  접근 허용 여부
</ParamField>

#### 응답

<ResponseField name="result" type="Boolean">
  설정 성공 여부
</ResponseField>

***

## 사용 흐름

### SMS 인증 흐름

1. **인증번호 요청**: `requestSMSAuth`로 SMS 발송
2. **사용자 입력**: 고객이 SMS로 받은 인증번호 입력
3. **인증 확인**: `confirmSMSAuth`로 검증 및 authHash 발급
4. **회원가입/비밀번호 변경**: authHash를 사용하여 계정 생성 또는 비밀번호 변경

### OTP 설정 흐름

1. **OTP 키 생성**: `setOtpKey`로 QR 코드 발급
2. **OTP 앱 등록**: Google Authenticator 등에서 QR 코드 스캔
3. **OTP 활성화**: `lockOtpKey`로 OTP 코드 검증 및 활성화

### 익명 로그인 흐름

1. **로그인 요청**: `requestAnonymousSignIn`으로 토큰 발급
2. **승인 대기**: `waitAnonymousSignIn`으로 승인 대기
3. **승인 처리**: 관리자가 `anonymousSignIn`으로 승인

## 관련 API

* [사용자 API](/api-reference/user-svc/user) - 회원가입 및 비밀번호 변경
* [Core 인증 API](/api-reference/core-svc/auth) - 마일리지 SMS 인증