Quickstart

Authentication

JoyToken uses API key authentication. Model calls should be sent from your server using the header for the selected compatible API.

Common Request Headers

Common headerRequiredDescription
Content-TypeYesapplication/json
X-Request-IDRecommendedLog, billing, and debugging correlation

Do not send both Authorization and X-API-Key on the same request. If both are present, the current gateway reads X-API-Key first.

Choose a Protocol

Authentication header:

Authorization: Bearer $JOY_TOKEN_API_KEY

The same header authenticates both POST /openai/v1/responses and POST /openai/v1/chat/completions.

Set JOY_TOKEN_OPENAI_BASE_URL from Environments before running the example.

curl "$JOY_TOKEN_OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: auth-example-001" \
  -d '{
    "model": "auto",
    "input": "ping"
  }'

Server-Side Proxy

Browsers and mobile apps should not hold JoyToken API keys. Recommended structure:

Browser / App -> Your backend -> JoyToken
export async function POST(req: Request) {
  const body = await req.json();
  const baseUrl = process.env.JOY_TOKEN_OPENAI_BASE_URL;
  const response = await fetch(`${baseUrl}/chat/completions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.JOY_TOKEN_API_KEY}`,
      "X-Request-ID": crypto.randomUUID(),
    },
    body: JSON.stringify(body),
  });
  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
}

To proxy the Responses API instead, send the same authenticated request to ${baseUrl}/responses. Keep the upstream path fixed in server code rather than accepting an arbitrary path from the browser.

Checks After Authentication

CheckFailure response
Key is valid and active403 invalid_api_key
IP, tier, and model policy403 policy_rejected
Wallet balance and key budget402 insufficient_quota
Request body validity400 invalid_request_error

Rotate an API Key

  1. Create a new key with the same or stricter policy.
  2. Write it to your server-side secret manager or environment variables.
  3. Send one verification request with X-Request-ID.
  4. Confirm logs and usage in JoyToken Console.
  5. Disable or revoke the old key.

Security Practices

PracticeReason
One key per app and environmentEasier budgets, policy, and usage attribution
Set budgets and tier limits for test keysCost control
Use separate keys for high-risk agentsAvoid unattended overspend
Revoke leaked keys immediatelyDo not keep using exposed keys