Developer

API-ключ, Basic, Bearer

↑ 1.3 Аутентификация и безопасность API · ← Предыдущая · → Следующая

Обязательно~5 мин чтенияУровень: junior

Зачем это аналитику и PM

В коллекции и в баге допуск выглядит по-разному: длинный ключ, строка Basic или Bearer. Путаница места, куда его класть, даёт ложный 401, а вставка секрета в чат даёт чужой доступ.

План темы

  • где передаются
  • как выглядят
  • где хранить
  • ротация ключей

Объяснение

API-ключ, Basic и Bearer — три частых способа предъявить допуск в HTTP. Все три отвечают на шаг «кто вы» или «какое приложение стучится». Что этому субъекту можно, решается отдельно.

Как три вида пропусков. Ключ — постоянный бейдж интеграции. Basic — имя и пароль на одной карточке. Bearer — разовый талон «предъявитель»: кто принёс талон, того и обслуживают, пока срок не вышел. Талон не кладут на видное место.

Как выглядят и где едут

Ключ — длинная случайная строка. Имя заголовка не универсально: встретите и X-Api-Key, и имя из документации партнёра. Класть ключ в query опасно: адрес попадает в журналы и историю. Если партнёр требует ключ только в адресе, это их ограничение, его фиксируют и не копируют в новые API без причины.

Basic собирает имя и пароль, кодирует их в Base64 и ставит в заголовок Authorization. Base64 — не шифрование, строку легко прочитать обратно. Поэтому Basic без HTTPS не используют. В примере ниже пароль вымышленный.

Bearer тоже живёт в Authorization, но значение — токен, часто выданный другим шагом входа. Слово Bearer значит «предъявитель». Сам токен может быть непрозрачной строкой или JWT. Формат токена не меняет имя заголовка.

СпособКуда обычно кладутНа кого похож
API-ключЗаголовок, имя смотрите в документацииДолгоживущий доступ приложения
BasicAuthorization: Basic ...Имя и пароль учётной записи
BearerAuthorization: Bearer ...Токен после входа или выдачи

Где хранить и как менять

Секрет не живёт в переписке, в скриншоте, в git и в экспортнутой коллекции «для всех». Ему место в хранилище секретов команды или в секретной переменной клиента запросов, которую не выгружают в общий файл. В примеры для задачи подставляют ***.

Ротация — плановая замена. Новый ключ начинают принимать, старый ещё работает короткий согласованный срок, затем старый гасят. Срок перекрытия берёте у владельца ключа, не из этой заметки. Утечку не ждут до плановой даты: ключ гасят сразу и выпускают новый. После гашения старые запросы получат 401, это ожидаемо, не поломка контракта полей.

Примеры

Три схемы заголовка. Хост учебный, секреты не настоящие. Строка Basic — Base64 от текста user:example, его можно раскодировать обратно, в этом и смысл предупреждения.

GET /orders HTTP/1.1
Host: api.example.com
X-Api-Key: ***
GET /orders HTTP/1.1
Host: api.example.com
Authorization: Basic dXNlcjpleGFtcGxl
GET /orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJ...

Нюансы и подводные камни

  • Ключ интеграции — не пользователь. Им нельзя изображать действие конкретного сотрудника, если контракт этого не обещает.
  • Один ключ на тест и на бой стирает границу стендов. Утечка тестовой коллекции тогда открывает прод.
  • Basic с боевым паролем в Postman легко уехать в экспорт. Пароль держат вне файла коллекции.
  • Bearer без пробела или с кавычками вокруг токена часто даёт 401, хотя токен живой.

Практика

По документации вашего тестового API или по учебному описанию выпишите: способ допуска, имя заголовка и куда секрет класть нельзя.

Ожидаемый результат: одна строка вида «Bearer в Authorization, значение в секретной переменной, в пример только маска». Если имя заголовка ключа неизвестно, стоит вопрос владельцу, а не выдуманное X-Api-Key как факт вашего сервиса.

Вопросы с ответами

Связано с блоком Developer

Связанные темы

Вид графа

Обратные ссылки