회원 인증 API

VeryChat 회원 인증 및 토큰 관리 API

인증번호 요청POST

프로젝트 ID와 핸들 ID를 통해 인증번호를 요청합니다.

엔드포인트

POST https://gapi.veryapi.io/auth/request-verification-code

요청 파라미터

필드명

타입

설명

projectId

string

해커톤 프로젝트 ID (필수)

handleId

string

사용자 핸들 ID (필수)

요청 예시

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "handleId": "user123"
}

• handleId가 @로 시작하는 경우 자동으로 @ 제거 후 처리됩니다.

• handleId에 해당하는 사용자가 존재하는 경우, 베리챗 푸시 알림 및 개인 메시지로 인증번호가 발송됩니다.

• 요청 처리 결과에 따라 성공/실패 상태가 반환됩니다.

인증번호 검증 (점유 인증)POST

인증번호의 유효성을 확인합니다. (토큰 발급 없음)

엔드포인트

POST https://gapi.veryapi.io/auth/verify-code

요청 파라미터

필드명

타입

설명

projectId

string

해커톤 프로젝트 ID (필수)

handleId

string

사용자 핸들 ID (필수)

verificationCode

number

6자리 인증번호 (필수)

요청 예시

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "handleId": "user123",
  "verificationCode": 123456
}

응답 (성공)

{
  "statusCode": 200,
  "message": "Verification code is valid"
}

응답 (실패)

{
  "statusCode": 401,
  "message": "Invalid or expired verification code."
}

• 이 API는 단순히 인증번호가 유효한지만 확인하며, 토큰을 발급하지 않습니다.

• 실제 로그인 토큰이 필요 없이 단순 점유 인증(사용자가 해당 계정에 접근할 수 있는지)만 확인하는 용도로 사용합니다.

• 실제 로그인 토큰이 필요한 경우 get-tokens API를 사용하세요.

토큰 발급 (인증번호 검증 + 토큰 생성)POST

인증번호를 검증하고 액세스 토큰과 리프레시 토큰을 발급받습니다.

엔드포인트

POST https://gapi.veryapi.io/auth/get-tokens

요청 파라미터

필드명

타입

설명

projectId

string

해커톤 프로젝트 ID (필수)

handleId

string

사용자 핸들 ID (필수)

verificationCode

number

6자리 인증번호 (필수)

요청 예시

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "handleId": "user123",
  "verificationCode": 123456
}

응답 (성공)

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "profileId": "user123",
    "profileName": "홍길동",
    "profileImage": "https://example.com/profile.jpg"
  },
  "statusCode": 200
}

• 인증번호를 검증하고 실제 로그인에 사용할 수 있는 액세스 토큰과 리프레시 토큰을 발급합니다.

• verify-code와 달리 실제 서비스 이용을 위한 인증 토큰을 제공합니다.

• 사용자 정보 포함: 토큰과 함께 사용자의 기본 정보(profileId, profileName, profileImage)를 반환합니다.

액세스 토큰 갱신POST

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

엔드포인트

POST https://gapi.veryapi.io/auth/refresh-tokens

요청 파라미터

필드명

타입

설명

projectId

string

해커톤 프로젝트 ID (필수)

handleId

string

사용자 핸들 ID (필수)

refreshToken

string

유효한 리프레시 토큰 (필수)

요청 예시

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "handleId": "user123",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

응답 (성공)

{
  "statusCode": 200,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

응답 (실패)

{
  "statusCode": 401,
  "message": "Invalid or expired refreshToken."
}

• 새로운 액세스 토큰과 함께 리프레시 토큰도 갱신됩니다.

• 만료된 리프레시 토큰으로는 갱신할 수 없습니다.

• projectId, handleId, refreshToken 모든 파라미터가 필수입니다.

토큰 검증POST

발급받은 JWT 토큰의 유효성을 검증합니다. (성능상 직접 검증 권장)

엔드포인트

POST https://gapi.veryapi.io/auth/validate-token

요청 파라미터

필드명

타입

설명

Authorization

string

Bearer <accessToken> (필수)

projectId

string

해커톤 프로젝트 ID (필수)

요청 예시

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

응답 (성공)

{
  "statusCode": 200,
  "data": {
    "valid": true,
    "payload": {
      "sub": "user123",
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "iat": 1640995200,
      "exp": 1640998800
    }
  }
}

응답 (실패)

{
  "statusCode": 401,
  "message": "Invalid or expired token"
}

• Authorization 헤더에 Bearer 토큰 형식으로 액세스 토큰을 전송해야 합니다.

• 권장사항: 성능상의 이유로 가능한 한 각 서버에서 직접 JWT 토큰을 검증하는 것을 권장합니다.

• 이 API는 토큰 검증이 복잡하거나 테스트 용도로 사용하시기 바랍니다.

인증 플로우 안내

1. 인증번호 요청 API를 통해 사용자에게 인증번호 발송

2. 사용자가 입력한 인증번호를 검증 API로 확인

3. 검증 성공 시 받은 액세스 토큰으로 다른 API 호출

4. 액세스 토큰 만료 시 리프레시 토큰으로 새 토큰 발급

5. 필요시 토큰 검증 API로 토큰 유효성 확인 (직접 검증 권장)