사용자 인증 요청 API
비볼디 REST API를 통해 사용자 정보를 조회하거나 설정을 변경하기 전, 보안 인증을 위한 액세스 토큰을 발급받으세요.
유효 기간이 제한된 토큰 기반 인증 방식을 통해 계정 보안을 강화하고 외부 위협으로부터 API 요청을 안전하게 보호할 수 있습니다.
발급된 토큰으로 X-Access-Token 헤더를 설정해 안전하게 API를 호출할 수 있습니다.
이 API는 퍼스널 요금제 이상에서만 사용할 수 있습니다.
POST
/api/user/v1/auth
{
"eml": "your@gmail.com"
}Request Parameters
- eml string
-
이메일.
비즈니스 요금제 이상에서 조직 내 추가된 사용자의 정보를 조회하거나 변경할 때 지정합니다.
퍼스널 및 프리미엄 요금제에서는 이 값이 무시됩니다.
{
"code": 0,
"message": "",
"result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Response Parameters
- code integer
- 응답 코드: 0 = 성공, 그 외 값 = 오류
- message string
- 응답 메시지입니다. 응답 코드가 0이 아니면, 오류 관련 메시지가 반환됩니다.
- result string
-
사용자 정보 조회 및 수정 요청 시, HTTP 헤더의
X-Access-Token항목에 추가해야 합니다.
토큰은 1분간 유효하며, 만료 후에는 재발급(본 API 재호출)이 필요합니다.
인증 토큰은 왜 필요한가요?
모든 API 요청은 인증을 통해 사용자 권한을 확인해야 합니다.
이 API는 다음 역할을 수행합니다.
- API 호출 주체 식별
- 사용자 권한 검증
- 비인가 요청 차단
- 보안 세션 관리
언제 이 API를 사용하나요?
<p>
본 API는 <a href="/url/api/user/retrieve">사용자 정보 조회(Retrieve)</a> 또는 <a href="/url/api/user/update">정보 수정(Update)</a>과 같이 계정 정보에 접근하는 API를 호출하기 전에 반드시 거쳐야 하는 인증 과정입니다.
</p>
<p>
발급된 인증 토큰은 이후 모든 요청의 HTTP 헤더에 X-Access-Token 항목으로 포함하여 전송해야 하며,
짧은 유효 기간을 통해 불필요한 장기 세션 노출을 차단하고 보안을 유지합니다.
</p>
토큰 유효시간 1분이 의미하는 것
1분이라는 짧은 유효시간은 보안을 위한 설계입니다.
토큰이 탈취되더라도 1분 후에는 자동으로 만료되어 피해를 최소화할 수 있습니다.
이 구조에서 올바른 구현 방식은 API 호출 직전에 토큰을 발급하고, 발급된 토큰을 즉시 사용하는 것입니다.
토큰을 장기간 저장해 재사용하는 방식은 인증 오류의 원인이 됩니다.
조회 대상 지정 방법 및 요금제 조건
비즈니스 요금제 이상의 조직 관리자는 eml 파라미터에 특정 조직원의 이메일 주소를 입력하여 인증을 수행할 수 있습니다.
이를 통해 조직 내 사용자의 정보를 조회하거나 관리하는 자동화 워크플로우를 구축할 수 있습니다.
단, 본 API는 퍼스널 요금제 등급 이상을 사용 중인 계정에서만 호출이 가능하므로 서비스 이용 전 요금제 환경을 확인하시기 바랍니다.
사용 시 주의사항
- 토큰은 외부에 노출되지 않도록 안전하게 저장해야 합니다.
- 클라이언트에 직접 노출하는 방식은 보안상 위험할 수 있습니다.
- 토큰 만료 시 자동 재발급 로직을 구현하는 것이 좋습니다.
- HTTPS 환경에서만 사용해야 합니다.