인증 가이드

본 문서는 RTZR STT OpenAPI의 인증 방식에 대해 안내합니다.

인증 방식

RTZR STT OpenAPI에서는 OAuth2 기반의 client_id와 client_secret 쌍과 JWT 기반 인증을 사용하고 있습니다.

• OAuth2 참고 링크: https://oauth.net/2/
• JWT 참고 링크: https://jwt.io/

참고사항

주의

토큰(Token)의 만료 기간은 6시간입니다. 주기적으로 토큰이 갱신될 수 있도록 /v1/authenticate을 통해 토큰을 갱신해야 합니다.

애플리케이션 등록 및 Secret 정보 확인

RTZR STT OpenAPI를 사용하기 위해서는 애플리케이션을 등록하고, API 연동 인증에 필요한 Secret 정보를 발급받아야 합니다. 아래 절차에 따라 이용해 주시기 바랍니다.

1. RTZR 디벨로퍼스 사이트 회원가입
2. 콘솔에 입장
3. API 연동에 필요한 SECRET (client_id, client_secret) 정보 발급

API 목록

Method	URL	Description
POST	/v1/authenticate	인증 토큰 요청

1) 인증 토큰 요청

HTTP 요청

POST https://openapi.vito.ai/v1/authenticate

요청 바디 (Request body)

application/x-www-form-urlencoded

Field	Type	Required
client_id	string	required
client_secret	string	required

샘플 코드

cURL

curl.post.auth.sh

curl -X "POST" "https://openapi.vito.ai/v1/authenticate" \
  -H "accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=${RTZR_CLIENT_ID}&client_secret=${RTZR_CLIENT_SECRET}"

Python

python.post.auth.py

import requests

resp = requests.post(
    "https://openapi.vito.ai/v1/authenticate",
    data={"client_id": "{RTZR_CLIENT_ID}", "client_secret": "{RTZR_CLIENT_SECRET}"},
)
resp.raise_for_status()
print(resp.json())

Java

AuthSample.java

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Scanner;

public class AuthSample {
    public static void main(String[] args) throws IOException {
        // Prefer Java system properties; fallback to environment variables
        String clientId = System.getProperty("rtzr.clientId", System.getenv("RTZR_CLIENT_ID"));
        String clientSecret = System.getProperty("rtzr.clientSecret", System.getenv("RTZR_CLIENT_SECRET"));

        if (clientId == null || clientSecret == null || clientId.isEmpty() || clientSecret.isEmpty()) {
            System.err.println("Missing credentials. Provide -Drtzr.clientId and -Drtzr.clientSecret or set RTZR_CLIENT_ID and RTZR_CLIENT_SECRET.");
            System.exit(1);
        }

        URL url = new URL("https://openapi.vito.ai/v1/authenticate");
        HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
        httpConn.setRequestMethod("POST");
        httpConn.setRequestProperty("accept", "application/json");
        httpConn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
        httpConn.setDoOutput(true);

        String data = "client_id=" + clientId + "&client_secret=" + clientSecret;

        byte[] out = data.getBytes(StandardCharsets.UTF_8);

        try (OutputStream stream = httpConn.getOutputStream()) {
            stream.write(out);
        }

        int status = httpConn.getResponseCode();
        try (InputStream responseStream = status / 100 == 2 ? httpConn.getInputStream() : httpConn.getErrorStream();
            Scanner s = new Scanner(responseStream).useDelimiter("\\A")) {
            String response = s.hasNext() ? s.next() : "";
            if (status / 100 == 2) {
                System.out.println(response);
            } else {
                System.err.println("HTTP " + status + ": " + response);
                System.exit(2);
            }
        }
    }
}

응답 바디 (Response Body)

응답이 성공한 경우 HTTP Status 200과 함께 아래와 같은 응답을 내려줍니다.

{
  "access_token": "{YOUR_JWT_TOKEN}",
  "expire_at": 1690377931
}

오류 코드

HTTP Status	Code	Name	Notes
400	H0001	BadRequest	잘못된 파라미터 요청
401	H0002	Unauthorized	인증 실패
500	E500	ServerError	서버 오류

아래는 응답 실패 시 예시입니다.

{
  "code": "H0002",
  "msg": "invalid credential"
}