احراز هویت و کلیدهای API

همه‌ی درخواست‌ها به API هوشوانا با یک کلید API احراز هویت می‌شوند. کلید مشخص می‌کند درخواست از طرف کدام حساب است، هزینه از کدام کیف پول کسر شود و کدام قوانین (مثل سقف هزینه یا مدل‌های مجاز) روی آن اعمال شود. این صفحه توضیح می‌دهد کلید را چطور بفرستید و چطور از آن محافظت کنید.

ارسال کلید

دو روش برای ارسال کلید پذیرفته می‌شود و هر دو روی همه‌ی endpointها کار می‌کنند:

اگر از SDK رسمی استفاده می‌کنید، لازم نیست هدر را دستی بسازید. SDK کلیدی را که به آن می‌دهید در هدر مناسب قرار می‌دهد.

# OpenAI style
curl https://hooshvana.ir/api/v1/models \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY"

# Anthropic style
curl https://hooshvana.ir/api/v1/messages \
  -H "x-api-key: $HOOSHVANA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-haiku-4.5", "max_tokens": 256, "messages": [{"role": "user", "content": "سلام"}]}'

درخواست بدون کلید یا با کلید نامعتبر با کد HTTP ۴۰۱ و کد خطای invalid_api_key رد می‌شود.

قالب کلید

• همه‌ی کلیدها با hv- شروع می‌شوند.
• کلید کامل فقط یک بار، در لحظه‌ی ساخت، نمایش داده می‌شود.
• هوشوانا فقط هش کلید را ذخیره می‌کند. یعنی حتی پشتیبانی هم نمی‌تواند کلید کامل شما را بازیابی کند.
• در داشبورد فقط پیشوند کلید (چند نویسه‌ی اول) نمایش داده می‌شود تا بتوانید کلیدها را از هم تشخیص دهید.

اگر کلیدی را گم کردید، کلید جدید بسازید و قبلی را باطل کنید.

نگهداری امن کلید

کلید API مثل رمز عبور کیف پول شماست. هر کسی آن را داشته باشد می‌تواند از اعتبار شما خرج کند. چند قاعده‌ی ساده:

کلید را در متغیر محیطی نگه دارید

# ~/.bashrc or ~/.zshrc
export HOOSHVANA_API_KEY="hv-..."

در پروژه‌ها از فایل .env استفاده کنید و حتماً آن را به .gitignore اضافه کنید:

# .env
HOOSHVANA_API_KEY=hv-...

echo ".env" >> .gitignore

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://hooshvana.ir/api/v1",
    api_key=os.environ["HOOSHVANA_API_KEY"],
)

هیچ‌وقت کلید را در کد سمت کاربر نگذارید

کلیدی که در کد مرورگر (React، Vue، اپلیکیشن موبایل یا افزونه‌ی مرورگر) قرار بگیرد، عملاً عمومی است. هر کاربری با باز کردن ابزار توسعه‌دهنده‌ی مرورگر یا باز کردن بسته‌ی اپلیکیشن می‌تواند آن را ببیند. همین‌طور کلید را در مخزن git، اسکرین‌شات، تیکت پشتیبانی یا پیام‌رسان‌ها قرار ندهید.

برای هر محیط کلید جداگانه بسازید

یک کلید برای توسعه‌ی محلی، یک کلید برای سرور آزمایشی و یک کلید برای سرور اصلی. این کار باعث می‌شود اگر یکی لو رفت، فقط همان را باطل کنید و در لاگ‌ها هم مصرف هر محیط جدا دیده شود.

الگوی پراکسی سمت سرور

اگر اپلیکیشن وب یا موبایل دارید، درخواست را از کلاینت به سرور خودتان بفرستید و سرور با کلید هوشوانا مدل را صدا بزند. به این ترتیب کلید هرگز از سرور خارج نمی‌شود و می‌توانید احراز هویت کاربران خودتان، محدودیت نرخ و اعتبارسنجی ورودی را هم روی سرور انجام دهید.

// server.js (Node.js + Express)
import express from "express";
import OpenAI from "openai";

const app = express();
app.use(express.json());

const client = new OpenAI({
  baseURL: "https://hooshvana.ir/api/v1",
  apiKey: process.env.HOOSHVANA_API_KEY,
});

app.post("/api/chat", async (req, res) => {
  // Authenticate your own user here before calling the model.
  const userMessage = String(req.body.message ?? "").slice(0, 4000);

  try {
    const completion = await client.chat.completions.create({
      model: "openai/gpt-4o-mini",
      max_tokens: 800,
      messages: [{ role: "user", content: userMessage }],
    });
    res.json({ reply: completion.choices[0].message.content });
  } catch (err) {
    res.status(502).json({ error: "model request failed" });
  }
});

app.listen(3001);

برای لایه‌ی دفاعی بیشتر، روی کلید سرور قانون بگذارید: فهرست IP مجاز (IP سرور شما)، سقف هزینه‌ی روزانه و محدود کردن به مدل‌هایی که واقعاً استفاده می‌کنید. اگر به هر دلیلی مجبورید کلید را در محیطی کم‌اعتمادتر استفاده کنید، فهرست referrer مجاز و سقف هزینه‌ی پایین ریسک را کم می‌کند، ولی جایگزین پراکسی نیست. جزئیات در قوانین کلید.

چرخش کلید

چرخش دوره‌ای کلید (مثلاً هر سه ماه یا پس از رفتن یکی از اعضای تیم) ریسک لو رفتن را کم می‌کند. روش پیشنهادی بدون قطعی:

1. یک کلید جدید با همان قوانین کلید قبلی بسازید.
2. کلید جدید را در متغیرهای محیطی یا سامانه‌ی مدیریت اسرار (secret manager) جایگزین کنید و سرویس را دوباره راه‌اندازی کنید.
3. در لاگ درخواست‌ها مطمئن شوید درخواست‌ها با کلید جدید می‌آیند و کلید قدیمی دیگر استفاده نمی‌شود.
4. کلید قدیمی را باطل کنید.

توقف موقت و ابطال

هر کلید یکی از این سه وضعیت را دارد:

اگر احتمال می‌دهید کلیدی لو رفته است، معطل نکنید: همان لحظه آن را باطل کنید، کلید جدید بسازید و لاگ‌ها را برای مصرف مشکوک بررسی کنید. اگر کلید تاریخ انقضا داشته باشد، پس از آن تاریخ با خطای key_expired رد می‌شود.

جمع‌بندی

• کلید را با Authorization: Bearer یا x-api-key بفرستید.
• کلید را فقط در سرور و در متغیر محیطی نگه دارید.
• برای هر محیط و هر سرویس کلید جدا بسازید و روی آن قانون بگذارید.
• به‌صورت دوره‌ای کلیدها را بچرخانید و کلیدهای بلااستفاده را باطل کنید.