> For the complete documentation index, see [llms.txt](https://docs.graspil.com/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/ru/api/auth.md).

# Авторизация

## Авторизация <a href="#id-93900fccba" id="id-93900fccba"></a>

Graspil API использует ключи API для обеспечения доступа к API. Ключ нужно передавать в каждом запросе одним из двух способов:

* заголовком `Api-Key: YOUR_API_KEY` (рекомендуется);
* query-параметром `?api-key=YOUR_API_KEY`.

{% tabs %}
{% tab title="PHP" %}

```php
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Api-Key: ' . $api_key]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

headers = {"Api-Key": api_key}
response = requests.get(url, headers=headers)
```

{% endtab %}

{% tab title="Js" %}

```javascript
fetch(url, {
  method: "GET",
  headers: {
    "Api-Key": api_key
  }
}).then();
```

{% endtab %}
{% endtabs %}

## Что такое ресурс

**Ресурс** — это подключённый к Graspil бот или канал, к которому относятся данные: пользователи, события, рассылки, автоматизации и т.д. У каждого ресурса есть свой публичный **ключ ресурса** (`resource_key`).

Ключ ресурса виден в адресной строке, когда вы открываете бота в разделе «**Мои боты**»: `https://app.graspil.com/resources/<ключ ресурса>`. Также список ресурсов, доступных вашему API-ключу, вместе с их ключами возвращает метод [`GET /v1/reports/resources`](/ru/api/reports.md).

## Где получить ключ

API-ключи создаются в разделе [«API-ключи»](https://app.graspil.com/api-keys) личного кабинета (меню профиля → «API-ключи» → «Создать ключ»). Один ключ может работать сразу со всеми вашими ботами.

При создании или редактировании ключа можно настроить:

* **Доступ к ресурсам** — «Все ресурсы» (по умолчанию) или только выбранные боты.
* **Доступ** — отдельно к публичному REST API и к MCP-серверу для AI-ассистентов. Для запросов к API у ключа должен быть включён доступ «API».
* **Права на действия** — для разделов «Отчёты», «Рассылки», «Автоматизации», «Лендинги», «Дашборды» можно выбрать «Полный доступ», «Без запуска» (создавать и редактировать, но не запускать рассылки, не публиковать автоматизации и т.п.) или «Только просмотр».
* **Срок действия** — бессрочный или на заданное число дней. Перед окончанием срока мы напомним по почте и в Telegram.

Там же видно, когда ключ последний раз использовался, а ненужный ключ можно отозвать.

### Контроль IP-адресов

Мы запоминаем, с каких IP-адресов обращаются по каждому ключу. Список адресов открывается кнопкой «**IP-адреса**» у ключа: для каждого адреса видно, когда с него впервые и в последний раз были запросы.

* Первый адрес ключа считается вашим — уведомления о нём не будет.
* Если по ключу пришёл запрос с нового адреса, мы пришлём уведомление на почту и в Telegram. Если новых адресов несколько, они придут одной сводкой — не чаще раза в час на ключ.
* Если адрес ваш (например, новый сервер интеграции), нажмите «**Это мои**» у адреса или «**Подтвердить все**» — по подтверждённым адресам уведомлений больше не будет.
* Если адрес вам незнаком — скорее всего, ключ попал к кому-то ещё. Отзовите его и создайте новый.

{% hint style="info" %}
Учёт IP ничего не блокирует: запросы с новых адресов выполняются как обычно. IPv6-адреса одной подсети /64 считаются одним адресом.
{% endhint %}

{% hint style="info" %}
Изменения ключа (отзыв, смена доступа, ресурсов или прав) начинают действовать в течение 10 минут.
{% endhint %}

## Когда нужно указывать ресурс

Если ключ выдан на **несколько ботов** (или на «Все ресурсы»), для методов, которые работают с конкретным ботом, нужно сообщить, к какому боту относится запрос.

Если ключ ограничен **ровно одним ботом** (в настройках ключа выбран один бот) — указывать ресурс не нужно, он определится автоматически.

### Способы указать ресурс

**1. Заголовок `Resource-Key`** — работает для всех методов:

```
Api-Key: YOUR_API_KEY
Resource-Key: RESOURCE_KEY
```

**2. Одной строкой в ключе** — удобно, если интеграция позволяет задать только одно значение ключа (например, поле «API-ключ» в стороннем сервисе). Порядок частей не важен:

```
Api-Key: YOUR_API_KEY:RESOURCE_KEY
```

**3. Параметр `resource_key`** — query-параметр `?resource_key=RESOURCE_KEY` работает для всех методов. Многие методы (рассылки, отчёты, автоматизации, лендинги, история переписки и др.) также принимают поле `resource_key` в теле `POST`-запроса — это указано в описании конкретного метода.

{% hint style="info" %}
Методы отправки данных — события и целевые действия (`send-event`, `send-target`), апдейты (`send-update` и др.), доп. поля пользователей (`send-user-field`) — не принимают `resource_key` в теле запроса. Для них используйте заголовок `Resource-Key`, query-параметр или ключ одной строкой.
{% endhint %}

{% hint style="warning" %}
В методах автоматизаций `resource_key` обязателен всегда, даже если ключ привязан к одному боту — см. [Автоматизации](/ru/api/automations.md).
{% endhint %}

## Ошибки авторизации

| Код   | Когда возникает                                                                                      |
| ----- | ---------------------------------------------------------------------------------------------------- |
| `401` | Ключ не передан, не найден, отозван или истёк срок его действия                                      |
| `403` | У ключа не включён доступ «API»                                                                      |
| `403` | Указанный ресурс недоступен ключу (не ваш бот или не входит в список ботов ключа)                    |
| `403` | Ключу не хватает прав на действие (например, запуск рассылки при правах «Без запуска»)               |
| `400` | Ресурс не указан, а ключ выдан на несколько ботов (`resource required` / `resource_key is required`) |