01Що це таке і як це працює
API key — це довгий рядок із літер і цифр, згенерований постачальником послуг. Коли ваш додаток робить запит до API, він включає ключ у заголовок запиту або рядок запиту (query string). Сервер зчитує ключ, шукає його у своїй базі даних і перевіряє, чи має цей ключ дозвіл на виконання запитаної дії. Ключі можуть мати обмежений область дії (scope), щоб обмежити доступні кінцеві точки (endpoints) та кількість запитів на хвилину. Вони прив'язані до платіжного акаунту або проєкту, тому використання зараховується правильному власнику. За замовчуванням ключі не зашифровані, тому їх слід надсилати через HTTPS, щоб уникнути перехоплення. Вони не підтверджують особу кінцевого користувача; вони підтверджують особу додатка, який робить запит.
API key — це як пароль для додатків. Ви додаєте його до свого запиту, а сервер перевіряє його, щоб вирішити, чи маєте ви право використовувати API.
02Що з цим робити
Цього тижня згенеруйте новий API key у панелі керування вашого провайдера та збережіть його в менеджері секретів або змінній середовища, але ніколи — у вихідному коді. Змініть усі ключі, які були зафіксовані у публічному репозиторії. Налаштуйте сповіщення про використання, щоб отримувати повідомлення у разі несподіваного стрибка обсягу запитів. Перевірте, які IP-адреси або домени мають доступ до кожного ключа, і обмежте їх, де це можливо. Задокументуйте, які члени команди мають доступ до яких ключів, і видаліть доступ для тих, кому він більше не потрібен.
03Як це вимірюється або помічається
Ви зрозумієте, що API key працює, коли запити повертають успішні відповіді замість помилок 401 або 403. У панелі керування вашого провайдера ви можете побачити кількість запитів, рівень помилок і затримку, згруповані за ключами. Якщо ви перевірите логи, то побачите рядок ключа в заголовках запитів. Якщо ключ анульовано або термін його дії закінчився, API поверне помилку автентифікації. Квоти використання зазвичай відображаються для кожного ключа окремо в розділі оплати або використання в панелі керування.
04Поширені помилки
- Жорстке кодування API keys безпосередньо у вихідному коді або конфігураційних файлах, які потрапляють у систему контролю версій
- Використання одного й того самого ключа в різних середовищах (розробка, тестування, продакшн) замість створення окремих ключів
- Відсутність обмежень для ключів, через що будь-яка IP-адреса або домен можуть їх використовувати
- Відсутність регулярної ротації ключів або їх оновлення після підозри на витік даних
- Зберігання ключів у текстових файлах у відкритому вигляді на спільних серверах або їх надсилання через незашифровані HTTP-з'єднання
05Обмеження
API keys не є заміною автентифікації користувача. Вони ідентифікують додаток, що робить запит, а не окремого користувача, який ним користується. Самі по собі вони не забезпечують детального контролю доступу; для цього потрібні OAuth токени або автентифікація на основі сесій. API keys працюють лише з сервісами, які прямо вимагають їх використання. Деякі API замість цього використовують OAuth, JWT токени або mutual TLS, і API key там не спрацює. Якщо сервіс не надає API, то керувати ключем не потрібно.
06Приклад роботи
Команда маркетингу використовує OpenAI's API для створення резюме відгуків клієнтів. Вони створюють ключ у панелі керування OpenAI, призначають його проєкту 'review-analysis' і встановлюють місячний ліміт витрат у $500. Їхній скрипт зчитує ключ зі змінної середовища під назвою OPENAI_API_KEY і додає його в заголовок Authorization кожного запиту. Коли скрипт запускається, API повертає резюме. Якщо ключ видалено або ліміт перевищено, API повертає помилку, і команда отримує сповіщення на електронну пошту.Запис вище написаний GetLoopLoop. Нижче — те, що про цей самий термін тримають незалежні каталоги. Жодне з цього не є джерелом цієї сторінки.
- Також називається
- API key
Той самий термін у Вікіпедії
Каталогізовано 6 мовами07Поширені запитання
Чи є API key тим самим, що й пароль?
Ні. API key ідентифікує програму або сервіс, що звертається до API, тоді як пароль ідентифікує людину, яка входить в обліковий запис. API keys зазвичай мають ширші та постійніші дозволи і не призначені для того, щоб людина їх запам'ятовувала або вводила вручну.
Коли мені варто використовувати API key замість OAuth або токенів?
Використовуйте API key для простих викликів server-to-server, де вам потрібно лише ідентифікувати проєкт, що робить запит, особливо якщо провайдер описує сценарій роботи з ключем. Використовуйте OAuth або короткострокові токени доступу, коли вам потрібно діяти від імені конкретного користувача, обмежувати права доступу або дозволити користувачам відкликати доступ без зміни облікових даних усього проєкту.
Звідки беруться API keys і хто їх видає?
Вони створюються сервісом, до якого ви хочете звернутися, через консоль розробника або панель керування цього провайдера. Провайдер прив'язує ключ до проєкту або облікового запису; ви несете відповідальність за його створення, копіювання та зберігання під час першого використання, оскільки більшість панелей керування показують повне значення лише один раз.
Чому мій запит повертає 401 або 403, хоча я надіслав ключ?
Помилка 401 зазвичай означає, що ключ відсутній, невірний або відкликаний, тоді як 403 означає, що ключ дійсний, але йому заборонено виконувати цю дію, часто через обмеження за IP, перевірку реферера або недостатній тарифний план. Перевірте, чи завантажується ключ із вашого secrets manager, чи надсилається він у заголовку, вказаному в документації, і чи не досягнуто ліміту запитів або квоти.
Що станеться, якщо я зафіксую (commit) API key у системі контролю версій?
Будь-хто, хто знайде репозиторій, зможе використовувати ключ від вашого імені, що може призвести до крадіжки квот, неочікуваних рахунків або анулювання вашого ключа провайдером. Негайно змініть ключ у панелі керування провайдера, видаліть його з історії git і перенесіть майбутні ключі у змінні оточення або менеджер секретів.
Чи мають термін дії API keys?
Деякі провайдери видають ключі, які ніколи не закінчуються, тоді як інші вимагають періодичної ротації або автоматичного завершення дії через певний період. За замовчуванням вважайте кожен ключ довготривалим і впроваджуйте ротацію у свій робочий процес, щоб анулювання одного ключа не порушило роботу продуктиву.
08Як про це питають уголос
Той самий термін словами, якими про нього питають асистента, а не набирають у рядку пошуку — написано із ситуації, тому кожне питання несе ту ситуацію, з якої виникло.
Так, але вам все одно потрібно змінити ключ. Негайно анулюйте його в панелі керування вашого провайдера, замініть його у ваших змінних оточення або менеджері секретів, а потім видаліть його з історії git за допомогою такого інструменту, як git filter-repo, перед тим як робити force push. Після цього відправте очищену історію та попросіть свою команду переклонувати репозиторій, щоб ніхто не зберігав старий ключ на своєму комп'ютері.
Перевірте чотири речі по черзі: чи є ключ від правильного проєкту, чи точно назва заголовка відповідає документації провайдера, чи ви звертаєтесь до базового URL для того середовища, до якого належить цей ключ, і чи ви не перевищили ліміт запитів. Якщо всі чотири пункти в нормі, перегенеруйте ключ один раз і протестуйте його за допомогою нового curl, перш ніж змінювати будь-який код додатка.
Ні, згенеруйте для них окремий ключ із мінімально можливим рівнем доступу, який дозволяє провайдер, і встановіть термін дії або нагадайте собі в календарі видалити його після завершення роботи. Використання вашого основного ключа пов'язує їхнє споживання ресурсів із вашим рахунком, і якщо ключ буде викрадено, анулювання доступу стане набагато серйознішим інцидентом.