Skip to main content

개요

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

Queries

refreshToken

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

GraphQL Signature

query RefreshToken($refreshToken: String!) {
  refreshToken(refreshToken: $refreshToken) {
    accessToken
    refreshToken
  }
}

파라미터

refreshToken
String!
required
기존 리프레시 토큰

응답

accessToken
String!
새로 발급된 액세스 토큰
refreshToken
String!
새로 발급된 리프레시 토큰

예제

query {
  refreshToken(refreshToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...") {
    accessToken
    refreshToken
  }
}

thirdParties

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

GraphQL Signature

query ThirdParties {
  thirdParties {
    id
    name
    authority
    trustedHosts
  }
}

응답

id
ID!
서드파티 사용자 ID
name
String!
서드파티 이름
authority
Int
권한 레벨
trustedHosts
String
신뢰할 수 있는 호스트 목록

Mutations

requestAnonymousSignIn

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

GraphQL Signature

mutation RequestAnonymousSignIn($type: String) {
  requestAnonymousSignIn(type: $type) {
    authId
    token
  }
}

파라미터

type
String
익명 로그인 타입 (선택사항)

응답

authId
ID!
인증 ID
token
String!
익명 로그인 토큰

예제

mutation {
  requestAnonymousSignIn(type: "kiosk") {
    authId
    token
  }
}

waitAnonymousSignIn

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

GraphQL Signature

mutation WaitAnonymousSignIn($token: String!, $authId: ID!) {
  waitAnonymousSignIn(token: $token, authId: $authId)
}

파라미터

token
String!
required
익명 로그인 토큰
authId
ID!
required
인증 ID

응답

result
String
로그인 결과 문자열

anonymousSignIn

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

GraphQL Signature

mutation AnonymousSignIn($token: String!) {
  anonymousSignIn(token: $token) {
    success
    error
  }
}

파라미터

token
String!
required
익명 로그인 토큰

응답

success
Boolean
성공 여부
error
String
에러 메시지 (실패 시)

requestSMSAuth

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

GraphQL Signature

mutation RequestSMSAuth($phone: String!) {
  requestSMSAuth(phone: $phone) {
    success
    error
  }
}

파라미터

phone
String!
required
인증번호를 받을 휴대폰 번호

응답

success
Boolean
SMS 발송 성공 여부
error
String
에러 메시지 (실패 시)

예제

mutation {
  requestSMSAuth(phone: "01012345678") {
    success
    error
  }
}

confirmSMSAuth

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

GraphQL Signature

mutation ConfirmSMSAuth($phone: String!, $number: String!) {
  confirmSMSAuth(phone: $phone, number: $number)
}

파라미터

phone
String!
required
인증번호를 받은 휴대폰 번호
number
String!
required
SMS로 받은 인증번호

응답

authHash
String!
인증 해시 (회원가입 또는 비밀번호 변경 시 사용)

예제

mutation {
  confirmSMSAuth(
    phone: "01012345678"
    number: "123456"
  )
}

verifyEmail

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

GraphQL Signature

mutation VerifyEmail($email: String!, $authHash: String!) {
  verifyEmail(email: $email, authHash: $authHash) {
    success
    error
  }
}

파라미터

email
String!
required
인증할 이메일 주소
authHash
String!
required
이메일로 받은 인증 해시

응답

success
Boolean
이메일 인증 성공 여부
error
String
에러 메시지 (실패 시)

requestEmailVerification

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

GraphQL Signature

mutation RequestEmailVerification {
  requestEmailVerification
}

응답

result
Boolean
이메일 발송 성공 여부
이 API는 인증이 필요하며, 로그인한 사용자의 이메일로 자동 발송됩니다.

revokeToken

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

GraphQL Signature

mutation RevokeToken {
  revokeToken {
    accessToken
    refreshToken
  }
}

응답

accessToken
String!
새로 발급된 액세스 토큰
refreshToken
String!
새로 발급된 리프레시 토큰

setOtpKey

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

GraphQL Signature

mutation SetOtpKey {
  setOtpKey {
    otpKey
    qrCode
  }
}

응답

otpKey
String!
OTP 시크릿 키
qrCode
String!
QR 코드 이미지 (Base64 또는 URL)

예제

mutation {
  setOtpKey {
    otpKey
    qrCode
  }
}
QR 코드를 Google Authenticator 또는 다른 OTP 앱으로 스캔하여 등록하세요.

lockOtpKey

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

GraphQL Signature

mutation LockOtpKey($input: LockOtpInput!) {
  lockOtpKey(input: $input) {
    success
  }
}

파라미터

input.otp
String!
required
OTP 앱에서 생성된 6자리 코드

응답

success
Boolean!
OTP 활성화 성공 여부

예제

mutation {
  lockOtpKey(input: { otp: "123456" }) {
    success
  }
}

getThirdPartyToken

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

GraphQL Signature

mutation GetThirdPartyToken($name: String!) {
  getThirdPartyToken(name: $name)
}

파라미터

name
String!
required
서드파티 시스템 이름

응답

token
String
서드파티 토큰

registerThirdParty

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

GraphQL Signature

mutation RegisterThirdParty($input: ThirdPartyInput!) {
  registerThirdParty(input: $input) {
    id
    name
    authority
    trustedHosts
  }
}

파라미터

input.name
String!
required
서드파티 이름
input.authorities
[String!]!
required
권한 목록
input.trustedHosts
String
신뢰할 수 있는 호스트 (선택사항)

응답

id
ID!
생성된 서드파티 사용자 ID
name
String!
서드파티 이름
authority
Int
권한 레벨
trustedHosts
String
신뢰할 수 있는 호스트

updateThirdParty

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

GraphQL Signature

mutation UpdateThirdParty($input: UpdateThirdPartyInput!) {
  updateThirdParty(input: $input) {
    id
    name
    authority
    trustedHosts
  }
}

파라미터

input.id
ID!
required
수정할 서드파티 사용자 ID
input.name
String
새로운 이름 (선택사항)
input.authorities
[String!]
새로운 권한 목록 (선택사항)
input.trustedHosts
String
새로운 신뢰 호스트 (선택사항)

modifyThirdPartyAccessOnAccommodation

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

GraphQL Signature

mutation ModifyThirdPartyAccessOnAccommodation(
  $accommodationId: ID!
  $thirdParty: String!
  $allow: Boolean!
) {
  modifyThirdPartyAccessOnAccommodation(
    accommodationId: $accommodationId
    thirdParty: $thirdParty
    allow: $allow
  )
}

파라미터

accommodationId
ID!
required
숙박 시설 ID
thirdParty
String!
required
서드파티 이름
allow
Boolean!
required
접근 허용 여부

응답

result
Boolean
설정 성공 여부

사용 흐름

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