인증

인증이 필요한 API는 Authorization 헤더에 Bearer 토큰을 포함해서 호출해요.

Authorization 헤더

Authorization: Bearer xoau.aB3xK9p2QwR7sT4uV1nM8oP5qL6rN0yZ7eF2gH4jK...

세션 액세스 토큰은 로그인, 회원가입, 소셜 로그인 완료 API 응답에서 받을 수 있어요.

공개 API 키를 사용하는 엔드포인트도 같은 Bearer 형식으로 키를 보내요.

curl 'https://api.youvico.com/users/me' \
  -H 'Authorization: Bearer xoau.aB3xK9p2QwR7sT4uV1nM8oP5qL6rN0yZ7eF2gH4jK...'

비로그인 요청

Authorization 헤더가 없으면 비로그인 사용자로 처리돼요.

비로그인 사용자가 접근할 수 있는 엔드포인트만 헤더 없이 호출할 수 있어요.

2단계 인증

2단계 인증이 활성화된 계정은 로그인 응답의 tfa가 true로 반환돼요.

이때 함께 반환된 accessToken은 2단계 인증 검증 전까지 제한된 상태예요.

{
  "accessToken": "xoau.aB3xK9p2QwR7sT4uV1nM8oP5qL6rN0yZ7eF2gH4jK...",
  "tfa": true
}

2단계 인증 > 검증에 같은 액세스 토큰과 OTP 또는 백업 코드를 보내면 토큰이 활성화돼요.

curl -X POST 'https://api.youvico.com/auth/tfa.verify' \
  -H 'Authorization: Bearer xoau.aB3xK9p2QwR7sT4uV1nM8oP5qL6rN0yZ7eF2gH4jK...' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "123456"
  }'

2단계 인증 검증이 필요한 상태에서 보호된 API를 호출하면 NEED_TFA_EXCEPTION 에러가 반환돼요.

{
  "message": "2단계 인증이 필요해요.",
  "code": "NEED_TFA_EXCEPTION",
  "tfa": true
}

세션 만료처럼 민감한 작업은 2단계 인증으로 발급한 ticket을 추가로 요구할 수 있어요.

해당 엔드포인트 문서의 Body에 ticket 필드가 있으면 2단계 인증 > 티켓 생성으로 티켓을 발급한 뒤 함께 보내요.