INTEGRATION DOCS

연동 문서

Veya SDK 및 API를 활용하여 안전한 본인인증을 구현하세요

SDK 선택

빠른 시작

대시보드에서 조직 생성

로그인 후 대시보드에서 조직을 생성하고 API 키와 Callback URL을 설정하세요.

인증 링크 생성 API 호출

서버에서 API를 호출하여 사용자별 일회용 인증 링크를 생성하세요.

사용자를 인증 페이지로 리다이렉트

생성된 링크로 사용자를 보내면 Veya가 본인인증을 처리합니다.

사용자 리디렉션 + 결과 조회

인증 완료 시 사용자가 callback_url?token=xxx로 리디렉션됩니다. 토큰으로 결과를 조회하세요.

인증

모든 API 요청은 HTTP Header에 API Key가 필요합니다:

http

X-API-Key: vk_live_1a2b3c4d5e6f7g8h9i0j

보안 주의: API 키는 절대 클라이언트 사이드 코드에 노출하지 마세요. 반드시 서버에서만 사용해야 합니다.

인증 링크 생성

POST/api/v1/verifications/link

특정 요구사항(소셜 로그인, 정보 수집 등)이 포함된 일회용 인증 링크를 생성합니다.

bash

# 1. 일회용 인증 링크 생성
curl -X POST "https://veya.kr/api/v1/verifications/link" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requirements": {
      "social": ["discord", "steam", "minecraft"],
      "dataCollection": ["gender", "birth_year"]
    },
    "expires_in": 3600
  }'

# 2. 콜백 받은 토큰으로 인증 결과 조회
curl -X GET "https://veya.kr/api/v1/verifications/result/abc123xyz..." \
  -H "X-API-Key: YOUR_API_KEY"

요청 파라미터

파라미터	타입	필수	설명
`requirements.social`	string[]	선택	요구할 소셜 로그인: `discord`, `steam`, `minecraft`
`requirements.dataCollection`	string[]	선택	수집할 추가 정보: `gender`, `nationality`, `birth_year`
`expires_in`	number	선택	링크 유효시간 (초, 기본값: 3600)

응답 예시 (200 OK)

json

{
  "token": "abc123xyz...",
  "url": "https://veya.kr/verify/abc123xyz...",
  "expires_at": "2025-12-08T21:00:00Z"
}

팁: API 키는 환경 변수로 관리하세요. 코드에 직접 하드코딩하지 마세요.

결과 수신 방법

인증 완료 후 결과를 받는 두 가지 방법이 있습니다. 둘 다 동일한 데이터를 반환합니다.

방법 1리디렉션 (Callback URL)

인증 완료 후 사용자가 callback_url?token=xxx로 리디렉션됩니다. 전달받은 토큰을 사용하여 결과를 조회할 수 있습니다.

1.사용자 인증 완료 → 7초 후 등록된 Callback URL로 자동 리디렉션

2.서버에서 토큰을 사용해 결과 조회 (이전 섹션의 언어별 예제 참조)

주의: 토큰은 일회용이며, 10분 후 만료됩니다.

방법 2웹훅 (Webhook)

Webhook URL을 설정하면 인증 완료 시 서버로 결과를 자동 전송합니다. 리디렉션 방식 대신 백그라운드에서 신뢰성 있게 결과를 받을 수 있습니다.

Webhook 헤더

http

Content-Type: application/json
X-Veya-Event: verification.completed
# Webhook Secret이 설정된 경우에만 아래 헤더가 포함됩니다.
X-Veya-Timestamp: 1771889843
X-Veya-Signature: v1=7b2c9a...

중요: 조직에 webhook_secret이 설정되어 있으면 서명 헤더가 포함됩니다. 시크릿이 없으면 웹훅은 서명 없이 전송되며, SDK 서명 검증 함수는 사용할 수 없습니다.

Webhook Payload

json

{
  "event": "verification.completed",
  "timestamp": "2026-02-23T20:13:40Z",
  "data": {
    "verification_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "user_id": "d3f2742a-5324-46db-8609-be8687572090",
    "is_adult": true,
    "is_duplicate": false,
    "birth_year": 2000,
    "gender": "MALE",
    "nationality": "LOCAL",
    "discord": ["697303019586451234"]
  }
}

팁: 10초 내 200-299 응답 필요. 실패 시 최대 3회 재시도 (1초, 2초, 3초 간격). 4xx 응답은 즉시 실패 처리됩니다.

Webhook 서명 검증 (보안)

웹훅 요청이 실제로 Veya에서 전송되었는지 확인하기 위해 x-veya-signature 및 x-veya-timestamp 헤더를 검증해야 합니다. 각 언어별 공식 SDK에 내장된 웹훅 검증 함수를 확인하세요.

bash

# 웹훅 서명 시스템은 SDK/백엔드 서버 구현용입니다. 
# Node.js, Python, 또는 Go 탭을 클릭하여 각 언어별 시그니처 검증 코드를 확인하세요.

응답 필드 설명

Webhook과 리디렉션 결과 조회 모두 동일한 필드를 반환합니다.

파라미터	타입	설명
`verification_id`	string	각 인증 거래의 고유 ID (트랜잭션 추적에 사용)
`user_id`	string	Veya 사용자 고유 ID (중복 확인에 사용)
`is_adult`	boolean	성인 여부 (만 18세 이상)
`is_duplicate`	boolean	이전에 이 조직에서 인증한 적 있는지 여부 (중복 처리 정책에 따라 동작)
`birth_year`	number	출생년도 (예: 2000)
`gender`	string	`MALE`, `FEMALE`, 또는 `UNKNOWN`
`nationality`	string	`LOCAL`, `FOREIGNER`, 또는 `UNKNOWN`
`discord`	string[]	Discord 사용자 ID 배열
`steam`	string[]	Steam 64-bit ID 배열
`minecraft`	string[]	Minecraft UUID 배열 (하이픈 제외)
`google`	string[]	Google 이메일 주소 배열
`naver`	string[]	Naver ID 배열
`kakao`	string[]	Kakao ID 배열

중요: is_duplicate의 동작은 조직의 중복 처리 정책에 따라 달라집니다. 자세한 내용은 아래 "중복 처리 정책" 섹션을 참고하세요.

선택적 필드: birth_year, gender, nationality 및 소셜 ID는 requirements에서 요청한 항목만 반환됩니다.

사용자 관리

인증된 사용자를 검색하고 관리할 수 있는 API입니다. 조직의 API Key로 인증하며, 해당 조직의 사용자만 관리할 수 있습니다.

GET/api/v1/verifications/api/search

사용자를 Veya ID, Discord ID, Steam ID, 또는 Minecraft UUID로 검색합니다.

bash

curl -X GET "https://veya.kr/api/v1/verifications/api/search?q=697303019586453545" \
  -H "X-API-Key: YOUR_API_KEY"

쿼리 파라미터: q — 검색어 (3자 이상)

응답 예시

json

{
  "data": [
    {
      "profile_id": "d3f2742a-5324-46db-8609-be8687572090",
      "matched_social": "discord",
      "matched_value": "697303019586453545",
      "is_adult": true,
      "is_duplicate": true,
      "is_banned": false,
      "last_verified": "2025-12-08T20:30:00Z",
      "discord": ["697303019586453545"],
      "steam": [],
      "minecraft": []
    }
  ],
  "count": 1
}

POST/api/v1/verifications/api/ban

특정 사용자를 차단합니다. 차단된 사용자는 더 이상 이 조직에서 인증할 수 없습니다.

bash

curl -X POST "https://veya.kr/api/v1/verifications/api/ban" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_id": "d3f2742a-...", "reason": "악용 의심"}'

파라미터	타입	필수	설명
`profile_id`	string	필수	차단할 사용자의 Veya 프로필 ID (UUID)
`reason`	string	선택	차단 사유 (관리 용도)

응답 예시

json

{
  "success": true,
  "message": "사용자가 차단되었습니다"
}

참고: 사용자를 차단하면 해당 사용자의 연동된 소셜 계정(Discord, Steam, Minecraft 등)도 함께 차단됩니다. 차단된 소셜 계정은 다른 신원으로 재사용할 수 없습니다.

DELETE/api/v1/verifications/api/ban/:profileId

차단된 사용자의 차단을 해제합니다.

bash

curl -X DELETE "https://veya.kr/api/v1/verifications/api/ban/d3f2742a-..." \
  -H "X-API-Key: YOUR_API_KEY"

응답 예시

json

{
  "success": true,
  "message": "차단이 해제되었습니다"
}

DELETE/api/v1/verifications/api/user/:profileId

사용자를 조직에서 삭제합니다. 해당 사용자의 인증 기록이 삭제되며, 다음 인증 시 중복으로 표시되지 않습니다.

bash

curl -X DELETE "https://veya.kr/api/v1/verifications/api/user/d3f2742a-..." \
  -H "X-API-Key: YOUR_API_KEY"

응답 예시

json

{
  "success": true,
  "message": "사용자가 조직에서 삭제되었습니다"
}

GET/api/v1/verifications/api/bans

조직의 차단된 사용자 목록을 조회합니다.

bash

curl -X GET "https://veya.kr/api/v1/verifications/api/bans" \
  -H "X-API-Key: YOUR_API_KEY"

응답 예시

json

{
  "data": [
    {
      "id": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
      "profile_id": "d3f2742a-5324-46db-8609-be8687572190",
      "reason": "악용 의심",
      "banned_at": "2025-12-08T20:30:00Z"
    }
  ],
  "count": 1
}

GET/api/v1/verifications/api/transaction/:id

인증 ID로 특정 인증 거래의 상태를 조회합니다. Webhook과 리디렉션 데이터에 포함된 verification_id를 사용합니다.

bash

curl -X GET "https://veya.kr/api/v1/verifications/api/transaction/a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "X-API-Key: YOUR_API_KEY"

응답 예시 (성공)

json

{
  "verification_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "completed",
  "success": true,
  "user_id": "d3f2742a-5324-46db-8609-be8687572090",
  "created_at": "2025-12-08T20:30:00Z"
}

응답 예시 (실패)

json

{
  "verification_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "failed",
  "success": false,
  "fail_reason": "duplicate",
  "created_at": "2025-12-08T20:30:00Z"
}

실패 사유 코드 (fail_reason)

banned사용자가 조직에서 차단됨

duplicate이미 인증한 사용자 (중복 차단 정책)

cooldown재인증 대기 기간 중

expired인증 링크 만료됨

pending인증 아직 완료되지 않음

중복 처리 정책

조직 설정에서 동일 사용자가 다시 인증을 시도할 때의 처리 방식을 선택할 수 있습니다. 대시보드의 조직 설정에서 변경 가능합니다.

allow허용 (기본값)

중복 인증을 허용합니다. is_duplicate가 true로 반환되지만 인증 자체는 성공합니다.

block차단

이미 인증한 사용자의 재인증을 차단합니다. fail_reason: "duplicate"로 실패 처리됩니다.

cooldown대기 기간

마지막 인증 후 설정된 기간(기본 30일) 동안 재인증을 차단합니다. 대기 기간 내 시도 시 fail_reason: "cooldown"으로 실패합니다.

소셜 중복 차단: 조직 설정에서 "소셜 중복 차단"을 활성화하면, 이미 다른 사용자에게 연동된 소셜 계정(Discord, Steam 등)의 재사용을 방지할 수 있습니다.

요청 한도 (Rate Limits)

API 오남용을 방지하고 안정적인 서비스를 제공하기 위해 Rate Limit이 적용됩니다. 한도 초과 시 429 Too Many Requests 에러가 반환됩니다.

인증 링크 생성: 초당 최대 10회
인증 결과 조회: IP당 1분 최대 60회
사용자 검색/관리: 초당 최대 5회

서버 측(SDK)에서 호출 시 Rate Limit에 걸리지 않도록 동시 요청 수를 적절히 조정해주세요. 지속적인 429 에러 발생 시 단기 차단될 수 있습니다.

에러 코드

400

Bad Request

잘못된 요청 형식

401

Unauthorized

유효하지 않은 API 키

403

Forbidden

권한 없음 또는 크레딧 부족

404

Not Found

인증 토큰을 찾을 수 없음

409

Conflict

이미 차단된 사용자 등 중복 요청

500

Internal Server Error

서버 오류

에러 응답 형식

json

{
  "success": false,
  "error": "Invalid API key"
}

크레딧 시스템

인증이 처리될 때마다 조직 소유자의 크레딧이 1 차감됩니다.

인증 요청(링크) 생성 시에는 크레딧이 차감되지 않습니다
인증 완료 시 1 크레딧이 차감됩니다 (인증 제공사 과금이 발생한 실패 건도 차감)
크레딧이 0이 되면 모든 대기 중인 인증 링크가 만료되고, 새 링크 생성이 거부됩니다
동시에 생성 가능한 대기 링크 수는 남은 크레딧의 50%로 제한됩니다
대시보드에서 남은 크레딧을 확인할 수 있습니다

크레딧 추가: 베타 기간동안 추가 크레딧 결제가 필요하시면 [email protected]로 문의해주세요.

도움이 필요하신가요?

API 사용 중 문제가 발생하셨나요? 언제든 문의해주세요.