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

هر درخواست به وب‌سرویس گیسو با یک کلید دسترسی (API Key) شناخته می‌شود. کلید می‌گوید درخواست از کدام حساب و کدام پروژه است، هزینه از کدام اعتبار کم شود و چه محدودیت‌هایی رویش باشد. این صفحه ساختن، فرستادن و امن نگه داشتن کلید را توضیح می‌دهد.

فرستادن کلید#

کلید را در سربرگ (هدر) Authorization و با پیشوند Bearer بفرستید؛ SDK رسمی OpenAI همین کار را خودش می‌کند. ابزاری که این هدر را نمی‌فرستد، می‌تواند کلید را در هدر X-API-Key بگذارد. کلید را در نشانی (Query String) نفرستید؛ نشانی‌ها در لاگ سرورها و مرورگر می‌مانند.

# Standard: the Authorization header
curl https://gisoo.pro/api/v1/me -H "Authorization: Bearer $GISOO_API_KEY"

# For tools that cannot set Authorization
curl https://gisoo.pro/api/v1/me -H "X-API-Key: $GISOO_API_KEY"

ساختن کلید#

1. بخش API اپ را باز کنید

   در gisoo.pro/app/api پروژه‌هایتان را می‌بینید. پروژه یعنی یک برنامه یا یک مشتری شما؛ مثلاً «ربات پشتیبانی» و «سایت فروشگاه».

2. یک پروژه بسازید

   برای هر پروژه می‌توانید بودجهٔ ماهانه و فهرست مدل‌های مجاز بگذارید. گزارش مصرف هم به تفکیک پروژه است.

3. برای پروژه کلید بسازید

   برای کلید نام، سقف هزینه، فهرست IP مجاز، محدودیت درخواست در دقیقه و تاریخ انقضا تعیین کنید؛ همه اختیاری‌اند.

4. کلید را همان لحظه کپی کنید

   کلید کامل فقط یک بار نشان داده می‌شود. ما فقط اثر رمزنگاری‌شدهٔ آن (hash) را نگه می‌داریم و خودش را نمی‌توانیم دوباره نشان دهیم. اگر گمش کردید، کلید تازه بسازید و قبلی را باطل کنید.

پیشوند کلید: sk-gisoo و sk-ntz#

کلیدی که در گیسو می‌سازید با sk-gisoo-v1- شروع می‌شود و کلیدی که در نِت اَرز ساخته شده با sk-ntz-v1-. گیسو برند هوش مصنوعی نِت اَرز است و حساب و اعتبار در هر دو یکی است؛ برای همین هر دو کلید روی هر دو نشانی کار می‌کنند و از همان اعتبار کم می‌کنند. پیشوند فقط برای این است که خودتان و ابزارهای اسکن رمز (Secret Scanning) کلید را بشناسید.

آزمودن کلید و دیدن محدودیت‌ها#

GET /me بدون هزینه است و می‌گوید کلید به کدام پروژه وصل است، چقدر اعتبار دارید و چه محدودیت‌هایی رویش هست. برای آزمودن کلید تازه همین را صدا بزنید:

{
  "object": "account",
  "balance": { "usd": "12.408114", "usd_display": "$12.4081" },
  "status": "active",
  "project": { "id": 42, "name": "support-bot" },
  "key": {
    "name": "production",
    "prefix": "sk-gisoo-v1-Xy7Q",
    "rpm_limit": 60,
    "spend_limit_usd": "20.00",
    "spent_usd": "3.591886",
    "expires_at": null
  },
  "limits": { "concurrency": 8, "max_request_kb": 20480 }
}

محدودیت‌هایی که روی هر کلید می‌گذارید#

بودجهٔ ماهانهٔ پروژه و سقف روزانهٔ حساب هم هست؛ جزئیاتش در مدیریت هزینه و محدودیت‌ها.

کلید را کجا نگه دارید#

• روی سرور، در متغیر محیطی یا مدیر رمز (Secret Manager). نه در کد، نه در مخزن گیت، نه در فایلی که همراه برنامه منتشر می‌شود.
• برای هر برنامه و هر محیط یک کلید جدا. کلید «توسعه» و «تولید» را جدا بسازید تا اگر یکی لو رفت، فقط همان را باطل کنید.
• برای هر کلید سقف هزینه بگذارید. کلیدی که لو برود، تا سقف خودش خرج می‌کند، نه تا ته اعتبار حساب.
• اگر سرورتان IP ثابت دارد، فهرست IP مجاز را پر کنید. آن‌وقت کلید لورفته از جای دیگری کار نمی‌کند.

نمونهٔ یک سرور کوچک که کلید را پیش خودش نگه می‌دارد و مرورگر فقط با آن حرف می‌زند:

// server.js — the browser talks to YOUR server; only the server knows the key.
import express from "express";
import OpenAI from "openai";

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

const gisoo = new OpenAI({ baseURL: "https://gisoo.pro/api/v1", apiKey: process.env.GISOO_API_KEY });

app.post("/chat", async (req, res) => {
  // your own checks first: signed-in user, message length, daily quota...
  const reply = await gisoo.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: String(req.body.message).slice(0, 4000) }],
    max_tokens: 400,
  });
  res.json({ text: reply.choices[0].message.content });
});

app.listen(3000);

# app.py — Flask: the key stays on the server
import os
from flask import Flask, request, jsonify
from openai import OpenAI

app = Flask(__name__)
gisoo = OpenAI(base_url="https://gisoo.pro/api/v1", api_key=os.environ["GISOO_API_KEY"])

@app.post("/chat")
def chat():
    message = str(request.json.get("message", ""))[:4000]
    reply = gisoo.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": message}],
        max_tokens=400,
    )
    return jsonify(text=reply.choices[0].message.content)

چرخش و ابطال کلید#

برای عوض کردن کلید بدون قطعی، این ترتیب را نگه دارید:

1. کلید تازه بسازید

   همان تنظیم‌های کلید قبلی را به کلید تازه بدهید.

2. کلید تازه را در برنامه بگذارید

   برنامه را با کلید تازه بالا بیاورید و با GET /me مطمئن شوید کار می‌کند.

3. کلید قبلی را باطل کنید

   از همان بخش API اپ. کلید باطل‌شده از همان لحظه با 401 api_key_revoked رد می‌شود و دوباره فعال نمی‌شود.

خطاهای احراز هویت#