Stream Token API

Generate a secure, single-use token for authenticating streaming workflow requests.

Overview

This endpoint generates a short-lived, single-use token for the streaming endpoint. Tokens are stored securely in Redis and automatically expire after their TTL period. This is step 1 of the two-step streaming flow.

Endpoint

• HTTP Method: GET

• URL: /api/v1/token

Features

Single-Use Security

Each token can only be used once — it is deleted from Redis after the first stream request.

Configurable TTL

Set a custom time-to-live between 1 and 300 seconds (default: 60s).

Bearer Key Auth

Tokens are generated under your API key — credits are charged to your organization.

Rate Limited

Server-derived rate limiting ensures fair usage across all consumers.

Authentication

Requires a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Request

Query Parameters

Name	Required	Type	Default	Description
ttl	No	number	60	Token lifetime in seconds (1–300)

No body content is required for this GET request.

Example Request

curl --request GET \
     --url "https://aitutor-api.vercel.app/api/v1/token?ttl=60" \
     --header "Authorization: Bearer YOUR_API_KEY"

With a custom TTL of 5 minutes:

curl --request GET \
     --url "https://aitutor-api.vercel.app/api/v1/token?ttl=300" \
     --header "Authorization: Bearer YOUR_API_KEY"

Response

A successful response returns the token and its TTL:

{
  "success": true,
  "token": "pub_tok_a1b2c3d4e5f6",
  "ttl": 60
}

Field	Type	Description
success	boolean	Always true on success
token	string	The single-use stream token (format: pub_tok_...)
ttl	number	Token lifetime in seconds

Response Headers

Header	Description
x-ratelimit-limit	Your rate limit per window
x-ratelimit-remaining	Remaining requests in window

Error Responses

401 Unauthorized

Missing or invalid API key.

{
  "error": "Unauthorized. Please provide a valid secret key.",
  "success": false
}

402 Payment Required

No credits remaining on the account.

{
  "error": "No credits remaining. Please add credits to continue using the service.",
  "success": false,
  "code": "invalid_billing"
}

429 Too Many Requests

Rate limit exceeded.

{
  "error": "Rate limit exceeded",
  "success": false
}

500 Internal Server Error

Token generation failed.

{
  "error": "Failed to create token, please try again or contact support.",
  "success": false,
  "code": "internal_server_error"
}

Code Examples

Python

import requests

url = "https://aitutor-api.vercel.app/api/v1/token?ttl=60"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}

response = requests.get(url, headers=headers)
token = response.json()["token"]
print(token)

Node.js

const response = await fetch(
  "https://aitutor-api.vercel.app/api/v1/token?ttl=60",
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);

const { token } = await response.json();
console.log(token);

cURL

curl --request GET \
     --url "https://aitutor-api.vercel.app/api/v1/token?ttl=60" \
     --header "Authorization: Bearer YOUR_API_KEY"

Additional Notes

• Single-Use: The token is deleted from Redis after its first use in a stream request.

• Auto-Expiry: Tokens expire automatically after the TTL period — unused tokens do not count against your API quota.

• Next Step: Use this token as a query parameter on the Stream Workflow endpoint to start receiving real-time responses.