Урок 3. Авторизация: ключи, токены, OAuth

Урок 3. Авторизация: ключи, токены, OAuth#

Цель: понять, как агент подтверждает, что он имеет право использовать API.

Зачем нужна авторизация#

API не должен быть открыт для всех. Иначе кто угодно мог бы:

• прочитать ваши данные
• изменить ваши данные
• использовать ваш счёт (например, отправлять SMS за ваш счёт)

Авторизация — это способ подтвердить, что именно вы (или ваш агент) имеете право использовать API.

Типы авторизации#

1. API Key (ключ API)

Самый простой способ. Вы получаете секретный ключ (строку символов) и передаёте его в каждом запросе.

Пример:

GET https://api.example.com/clients
Authorization: Bearer sk_test_1234567890abcdef

Где получить: в настройках сервиса (обычно раздел «API Keys», «Settings», «Developers»).

Безопасность: храните ключ в секрете, не публикуйте его в коде, не передавайте посторонним.

2. Bearer Token (токен)

Похоже на API Key, но токен может иметь срок действия (например, 1 час). После истечения нужно получить новый токен.

Пример:

GET https://api.example.com/clients
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Где получить: обычно через отдельный запрос (логин + пароль → токен).

3. OAuth 2.0 (для доступа к аккаунтам пользователей)

Используется, когда агент должен действовать от имени пользователя (например, отправлять email от имени пользователя через Gmail).

Как работает:

1. Пользователь кликает «Разрешить доступ» на странице сервиса (например, Google)
2. Сервис выдаёт токен доступа (access token)
3. Агент использует токен для запросов от имени пользователя

Пример: Zapier просит доступ к вашему Google Sheets → вы разрешаете → Zapier получает токен → Zapier может читать/писать в ваши таблицы.

Безопасность: пользователь всегда контролирует, какие права даёт агенту (только чтение / полный доступ).

Как получить API Key#

Пример: Telegram Bot API

1. Напишите боту @BotFather в Telegram
2. Отправьте команду /newbot
3. Введите имя бота
4. Введите username бота (должен заканчиваться на bot)
5. BotFather выдаст вам токен (API Key): 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
6. Используйте этот токен для отправки запросов в Telegram Bot API

Пример запроса:

GET https://api.telegram.org/bot1234567890:ABCdefGHIjklMNOpqrsTUVwxyz/getMe

Ответ:

{
  "ok": true,
  "result": {
    "id": 1234567890,
    "is_bot": true,
    "first_name": "Мой бот",
    "username": "my_bot"
  }
}

Где хранить ключи#

Никогда не храните ключи в коде или публичных местах!

Храните ключи в:

• переменных окружения (environment variables) — если вы запускаете агента на сервере
• секретном хранилище сервиса (например, в n8n есть раздел «Credentials», где можно сохранить ключи)
• менеджере паролей (1Password, Bitwarden) — если вы работаете локально

Никогда не публикуйте ключи в GitHub, не отправляйте их в чатах, не показывайте на скриншотах.