> ## 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 기반 인증 API

## 개요

Core 서비스의 인증 도메인은 SMS 기반 인증 시스템을 제공합니다. 마일리지 결제 및 예약 확인을 위한 SMS 인증번호 발송과 검증 기능을 제공합니다.

## Mutations

### requestMileageSMSAuth

마일리지 결제 또는 예약 확인을 위한 SMS 인증번호를 요청합니다.

#### GraphQL Signature

```graphql theme={null}
mutation RequestMileageSMSAuth($phone: String!, $type: String) {
  requestMileageSMSAuth(phone: $phone, type: $type) {
    success
    _dev_sentAuth
  }
}
```

#### 파라미터

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

<ParamField path="type" type="String">
  인증 타입:

  * `"reservation"`: 예약 확인용 인증
  * 기본값: 마일리지 결제용 인증
</ParamField>

#### 응답

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

<ResponseField name="_dev_sentAuth" type="String">
  개발 환경에서만 반환되는 인증번호 (디버깅용)
</ResponseField>

#### 예제

<CodeGroup>
  ```graphql Request theme={null}
  mutation {
    requestMileageSMSAuth(
      phone: "01012345678"
      type: "reservation"
    ) {
      success
    }
  }
  ```

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

#### Rate Limiting

* **제한**: 10분 동안 동일 번호로 최대 5회
* **만료**: 인증번호는 70초 후 만료

#### 에러 처리

<ResponseField name="FAILED_TO_SEND_SMS">
  SMS 발송 실패 시 반환됩니다. SMS 서비스 상태를 확인하세요.
</ResponseField>

***

### confirmMileageSMSAuth

SMS로 전송된 인증번호를 검증하고 인증 토큰을 발급합니다.

#### GraphQL Signature

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

#### 파라미터

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

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

#### 응답

<ResponseField name="authHash" type="String!">
  인증 성공 시 발급되는 ULID 형식의 인증 토큰

  * 유효기간: 30분
  * 다른 API 요청 시 인증 토큰으로 사용
</ResponseField>

#### 예제

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

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

#### Rate Limiting

* **제한**: 1분 동안 동일 번호로 최대 10회
* **실패 시**: 제한 초과 시 해당 번호의 인증번호가 삭제됩니다

#### 에러 처리

<ResponseField name="AUTH_NUMBER_NOT_MATCH">
  인증번호가 일치하지 않습니다. 올바른 인증번호를 입력하세요.
</ResponseField>

<Warning>
  인증번호 검증 실패 시 10회 제한에 도달하면 새로운 인증번호를 요청해야 합니다.
</Warning>

## 사용 흐름

1. **인증번호 요청**: `requestMileageSMSAuth`로 SMS 발송
2. **사용자 입력**: 고객이 SMS로 받은 6자리 번호 입력
3. **인증 확인**: `confirmMileageSMSAuth`로 검증 및 토큰 발급
4. **토큰 사용**: 발급받은 authHash를 다른 API 요청에 사용

## 관련 API

* [마일리지 API](/api-reference/core-svc/mileage) - 인증 토큰을 사용한 마일리지 결제
* [예약 API](/api-reference/core-svc/reservation) - 인증 토큰을 사용한 예약 확인