Authentication Guide

This document describes the authentication method for RTZR STT OpenAPI.

Authentication method

RTZR STT OpenAPI uses an OAuth2 client_id/client_secret pair and JWT-based authentication.

• OAuth2 reference: https://oauth.net/2/
• JWT reference: https://jwt.io/

Notes

caution

Token expiration time is 6 hours. You must periodically refresh the token via /v1/authenticate.

Application registration and Secret

To use RTZR STT OpenAPI, register an application and issue the Secret required for API authentication.

1. Sign up on the RTZR Developers site: https://developers.rtzr.ai/signup
2. Open the Console: https://developers.rtzr.ai/console/
3. Issue SECRET (client_id, client_secret)

API list

Method	URL	Description
POST	/v1/authenticate	Request auth token

1) Request auth token

HTTP request

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

Sample code

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

On success, the API returns HTTP 200 with the payload below.

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

Error codes

HTTP Status	Code	Name	Notes
400	H0001	BadRequest	Invalid params
401	H0002	Unauthorized	Auth failed
500	E500	ServerError	Server error

Example failure response:

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