---
title: احراز هویت در Stard API
url: https://stard-market.ir/docs/authentication
markdown: https://stard-market.ir/docs/authentication.md
language: fa
updated: 2026-11-18
description: هر درخواست با هدر Authorization: Bearer و کلید API احراز هویت می‌شود؛ کلید هرگز نباید در URL یا کد سمت کاربر بیاید.
---

# احراز هویت در Stard API

> هر درخواست با هدر Authorization: Bearer و کلید API احراز هویت می‌شود؛ کلید هرگز نباید در URL یا کد سمت کاربر بیاید.

## هدر Authorization

کلید را فقط در هدر بفرست:

**درخواست**

```http
GET /api/v1/ping HTTP/1.1
Host: stard-market.ir
Authorization: Bearer sk_live_…
```

*⛔*

کلید در query string (`?api_key=`) با خطای `key_in_url` رد می‌شود، چون URLها در لاگ سرورها و تاریخچه‌ی مرورگر می‌مانند.

## فقط سمت سرور

کلید API دسترسی خرید از کیف پول تو را دارد. آن را هرگز در اپ موبایل، افزونه‌ی مرورگر یا جاوااسکریپت سمت کاربر نگذار. اگر کلاینت لازم دارد، از سرور خودت به‌عنوان واسطه استفاده کن.

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

| HTTP | code | معنی |
|---|---|---|
| 401 | `missing_api_key` | هدر Authorization نیامده |
| 401 | `invalid_authorization_header` | قالب هدر اشتباه است |
| 401 | `invalid_api_key` | کلید وجود ندارد |
| 401 | `api_key_revoked` / `api_key_expired` | کلید باطل یا منقضی شده |
| 403 | `insufficient_scope` | کلید اجازه‌ی این کار را ندارد |
| 403 | `developer_suspended` | حساب توسعه‌دهنده غیرفعال شده |
| 429 | `too_many_auth_failures` | تلاش‌های ناموفق زیاد از یک IP؛ ۱۰ دقیقه صبر کن |

**نمونه — 401**

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "کلید API نامعتبر است.",
    "param": null,
    "request_id": "req_kOJImCbYQBR8TFvCeGON"
  }
}
```
