المصادقة

جميع طلبات API إلى كلمات تتطلب مفتاح API. تعلّم كيفية إيجاد مفتاحك واستخدامه وتأمينه.

الحصول على مفتاح API الخاص بك

تُنشأ مفاتيح API وتُدار في لوحة التحكم ← صفحة مفاتيح API. انقر على "إنشاء مفتاح API"، أعطِه اسماً (مثل "الإنتاج"، "التطوير")، وانقر على "إنشاء".Dashboard → API Keys

كيفية إيجاد مفتاحك في لوحة التحكم:

1سجّل الدخول إلى kalimalab.com وافتح لوحة التحكم.
2انقر على "مفاتيح API" في الشريط الجانبي الأيسر.API Keys
3انقر على "إنشاء مفتاح API"، أدخل تسمية وصفية (مثل "production")، وأكّد.Create API Key
4انسخ المفتاح المعروض — يبدأ بـ klmt_live_.
5الصقه في ملف .env أو مدير الأسرار فوراً.

⚠انسخ فوراً

يُعرض مفتاح API مرة واحدة فقط عند الإنشاء. إذا فقدته، يجب إلغاؤه وإنشاء مفتاح جديد. خزّنه في مدير الأسرار أو ملف .env فوراً.

يمكنك أيضاً إلغاء أي مفتاح في أي وقت من صفحة مفاتيح API نفسها. يسري الإلغاء في غضون ميلي ثانية — راجع معالجة الأخطاء للاطلاع على الاستجابة التي سيتلقاها المتصلون.معالجة الأخطاء

طريقتان للمصادقة

تقبل كلمات مفتاح API إما في ترويسة Authorization (موصى به) أو ترويسة x-api-key.

موصى بهBearer token (ترويسة Authorization)

bash

curl https://api.kalimalab.com/v1/words/random \  -H "Authorization: Bearer klmt_live_your_key"

typescript

const response = await fetch('https://api.kalimalab.com/v1/words/random', {  headers: {    Authorization: `Bearer ${process.env.KALIMALAB_API_KEY}`,  },})

ترويسة x-api-key

bash

curl https://api.kalimalab.com/v1/words/random \  -H "x-api-key: klmt_live_your_key"

typescript

const response = await fetch('https://api.kalimalab.com/v1/words/random', {  headers: {    'x-api-key': process.env.KALIMALAB_API_KEY!,  },})

مقارنة جنباً إلى جنب (cURL)

bash

# Method 1: Bearer token (recommended)curl https://api.kalimalab.com/v1/words \  -H "Authorization: Bearer klmt_live_your_key_here"# Method 2: x-api-key headercurl https://api.kalimalab.com/v1/words \  -H "x-api-key: klmt_live_your_key_here"

SDK (يتعامل مع المصادقة تلقائياً)

typescript

import { KalimaLab } from '@kalimalab/sdk'// The SDK reads KALIMALAB_API_KEY from environment by defaultconst client = new KalimaLab({ apiKey: process.env.KALIMALAB_API_KEY! })// All requests are automatically authenticatedconst word = await client.words.random()

✕لا تُكشف مفتاحك على جانب العميل أبداً

يجب استخدام مفاتيح API في الكود من جانب الخادم فقط. لا تضمّنها أبداً في JavaScript المتصفح أو ملفات مكوّنات React أو حزم تطبيقات الجوال أو مستودعات git العامة. أي شخص يحصل على مفتاحك يمكنه تقديم طلبات تُحسب على حصتك وفوترتك.

أفضل ممارسات الأمان

لا تُكشف مفتاحك على جانب العميل أبداً

يجب استخدام مفاتيح API من جانب الخادم فقط. لا تضمّنها أبداً في JavaScript المتصفح أو حزم تطبيقات الجوال أو المستودعات العامة.

استخدم متغيرات البيئة

خزّن المفاتيح في ملفات .env (لا تُرفع إلى git أبداً) أو في مدير أسرار منصة النشر (Vercel وFly.io وRailway وغيرها).

مفتاح واحد لكل بيئة

أنشئ مفاتيح منفصلة للتطوير والتجهيز والإنتاج. بهذه الطريقة يمكنك إلغاء مفتاح مخترق دون التأثير على البيئات الأخرى.

دوّر المفاتيح بشكل دوري

أنشئ مفتاحاً جديداً، وحدّث متغيرات البيئة، ثم ألغِ المفتاح القديم. لا توقف إذا اتبعت هذا الترتيب.

استخدام متغيرات البيئة في Node.js

.env

# .env (never commit this file)KALIMALAB_API_KEY=klmt_live_your_key_here

lib/kalimalab.ts

import { KalimaLab } from '@kalimalab/sdk'if (!process.env.KALIMALAB_API_KEY) {  throw new Error('KALIMALAB_API_KEY is not set')}export const kalimalab = new KalimaLab({  apiKey: process.env.KALIMALAB_API_KEY,})

تدوير المفاتيح

لتدوير مفتاح API دون توقف، اتبع هذا التسلسل:

1انتقل إلى لوحة التحكم ← مفاتيح API وانقر على "إنشاء مفتاح API".
2أعطِه نفس اسم المفتاح الذي تُدوّره (مثل "Production").
3حدّث متغير بيئة الإنتاج لاستخدام المفتاح الجديد.
4انشر / أعد تشغيل خدمتك.
5بعد التأكد من عمل المفتاح الجديد، عد إلى مفاتيح API وألغِ المفتاح القديم.

ماذا يحدث عند إلغاء مفتاح؟

تُرفض المفاتيح الملغاة فوراً — في غضون ميلي ثانية من الإلغاء. أي طلب بمفتاح ملغى سيتلقى:

json

{  "data": null,  "error": {    "code": "ERR_AUTH_REVOKED",    "message": "This API key has been revoked. Generate a new key from your dashboard."  },  "meta": { "requestId": "req_01j9..." }}

✕الإلغاء دائم

بمجرد الإلغاء، لا يمكن إعادة تفعيل المفتاح. يجب إنشاء مفتاح جديد.

رموز أخطاء المصادقة

الرمز	حالة HTTP	المعنى
ERR_AUTH_MISSING	401	لم يُقدَّم مفتاح API في ترويسات الطلب.
ERR_AUTH_INVALID	401	مفتاح API غير موجود أو أُدخل بشكل خاطئ.
ERR_AUTH_REVOKED	401	مفتاح API موجود لكنه مُلغى.

Edit this page on GitHub

Previousالبدء السريع Nextحدود الطلبات