مستندات تترا

احراز هویت

دریافت توکن دسترسی با api_key و secret و ابطال آن

مقدمه

گیت‌وی تترا از احراز هویت مبتنی بر توکن استفاده می‌کند. کسب‌وکار با ارسال api_key و secret به سرویس Login، یک توکن کوتاه‌مدت Sanctum دریافت می‌کند. این توکن در تمام فراخوانی‌های بعدی گیت‌وی در هدر Authorization: Bearer ارسال می‌شود. توکن پس از یک ساعت منقضی می‌شود و در صورت نیاز می‌توان آن را زودتر ابطال کرد.

هشدار:

api_key و secret معادل همان کلیدهایی هستند که پیش‌تر برای امضای HMAC استفاده می‌شدند. این مقادیر را با دقت نگهداری کنید.

توجه:

POST /gateway/v1/auth/token تنها سرویسی است که Idempotency-Key نمی‌خواهد. تمام سرویس‌های دیگر گیت‌وی به این هدر نیاز دارند.

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

۱. دریافت توکن (Login)

Endpoint

POST /gateway/v1/auth/token

هدرها

هدرمقدارالزامی
Acceptapplication/jsonبله
Content-Typeapplication/jsonبله

پارامترها

پارامترنوعالزامیتوضیح
api_keystringبلهکلید API کسب‌وکار
secretstringبلهکلید مخفی کسب‌وکار

نمونه درخواست:

json
{
  "api_key": "YOUR_API_KEY",
  "secret": "YOUR_SECRET"
}

نمونه کد

php
<?php
$payload = json_encode([
    'api_key' => 'YOUR_API_KEY',
    'secret'  => 'YOUR_SECRET',
]);
$ch = curl_init('https://back.tetra.land/gateway/v1/auth/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
$token = $data['data']['token'];

امتحان کنید

POST/gateway/v1/auth/tokenامتحان کنید
api_key*
secret*
نمایش JSON ارسالی 
{
  "api_key": "کلید API شما",
  "secret": "کلید مخفی شما"
}

پاسخ‌ها

json
{
  "data": {
    "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "expires_at": "2026-08-18T13:00:00.000000Z"
  },
  "meta": {
    "status": true,
    "message": "Operation completed successfully.",
    "tracking_code": "260818_XXXXXX"
  }
}

۲. ابطال توکن (Logout)

Endpoint

POST /gateway/v1/auth/logout

هدرها

هدرمقدارالزامی
Acceptapplication/jsonبله
AuthorizationBearer {gateway_token}بله
Idempotency-Keyیک کلید یکتابله

پارامترها

این سرویس بدنه‌ای دریافت نمی‌کند.

توجه:

این عملیات همه توکن‌های فعال api_key را ابطال می‌کند، نه فقط توکن جاری.

نمونه کد

php
<?php
$ch = curl_init('https://back.tetra.land/gateway/v1/auth/logout');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Authorization: Bearer YOUR_GATEWAY_TOKEN',
    'Idempotency-Key: ' . uniqid('', true),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

امتحان کنید

POST/gateway/v1/auth/logoutامتحان کنید

پاسخ‌ها

json
{
  "data": null,
  "meta": {
    "status": true,
    "message": "Operation completed successfully.",
    "tracking_code": "260818_XXXXXX"
  }
}