Что такое API-ключ

API (Application Programming Interface) позволяет приложениям взаимодействовать друг с другом, обмениваться данными и использовать функции сторонних сервисов без необходимости знать внутреннее устройство системы. Например, приложение с прогнозом погоды может получать актуальные данные через OpenWeather API, а сайт с картой — отображать карты и маршруты при помощи Google Maps API.

Чтобы контролировать доступ к таким интерфейсам, разработчики используют API-ключи. Их можно сравнить с ключ-картой, которая позволяет пройти в определенное помещение: ключ предъявляется при обращении к сервису, а сервер проверяет его и определяет, разрешен ли запрашиваемый доступ. В зависимости от настроек API-ключ также позволяет ограничивать число запросов и управлять доступом к отдельным функциям приложения.

Как правило, API-ключ идентифицирует приложение, а не конечного пользователя. Поэтому его не всегда достаточно для полноценной аутентификации и авторизации. Если сервису необходимо проверить личность пользователя и определить его индивидуальные права, могут потребоваться дополнительные механизмы, например токены доступа.

Как работает API-ключ на практике

Основа работы API-ключей — обмен HTTP-запросами между приложением и сервером. Разработчик передает ключ вместе с запросом, сервер проверяет его и в зависимости от результата возвращает запрошенные данные или отклоняет обращение. Этот процесс можно разделить на четыре шага:

1. Шаг первый. Приложение формирует запрос. Когда приложению нужно получить данные, оно отправляет HTTP-запрос к API. Например, приложение погоды запрашивает актуальную температуру через OpenWeather API.

2. Шаг второй. Разработчик передает API-ключ. Ключ обычно указывается в заголовке запроса (HTTP header) — служебной части HTTP-сообщения, в которой содержатся дополнительные параметры. В некоторых API используется заголовок вида Authorization: Bearer <ключ>, а в отдельных случаях ключ передается как параметр URL. Конкретный способ зависит от требований сервиса.

3. Шаг третий. Сервер проверяет ключ и права доступа. Получив запрос, сервер извлекает ключ и проверяет, действителен ли он, не отозван ли и разрешает ли он выполнить запрашиваемую операцию. Также сервер может проверять ограничения по количеству запросов и доступные квоты — установленные лимиты использования API.

4. Шаг четвертый. Сервер возвращает ответ. Если проверка пройдена успешно, сервер обрабатывает запрос и отправляет ответ, например данные о погоде или информацию для отображения карты. Если ключ недействителен, у приложения нет необходимых прав или превышен лимит запросов, сервер может отклонить обращение и вернуть соответствующий код ошибки HTTP.

API-ключ vs токен доступа: в чём разница

API-ключ и токен доступа — это учетные данные, которые используются при обращении к API. Их часто путают, поскольку оба инструмента можно передавать вместе с HTTP-запросом и использовать для контроля доступа к ресурсам. Однако они различаются по назначению, сроку действия и способу предоставления прав.

Токен доступа — это учетные данные, которые позволяют приложению обращаться к API в пределах предоставленных разрешений. В частности, OAuth-токены используются для делегированного доступа: пользователь разрешает приложению взаимодействовать с определенными ресурсами от его имени.

Токен доступа обычно имеет ограниченный срок действия. После его истечения приложение может получить новый токен с помощью токена обновления (refresh token), если такой механизм предусмотрен сервисом. В этом случае пользователю не требуется повторно проходить аутентификацию при каждом обновлении токена.

API-ключ — это строка символов, которая позволяет идентифицировать приложение при обращении к API. Как правило, API-ключ используется как статические учетные данные: он может действовать длительное время, пока не будет отозван, заменен или не истечет срок его действия.

API-ключи широко применяются для взаимодействия между серверными приложениями (server-to-server), а также для идентификации приложений.

API-ключ обычно не обновляется автоматически. Если ключ отозван или скомпрометирован, разработчику необходимо выпустить новый ключ и заменить старый.

Для наглядных различий API-ключа и токена доступа воспользуемся таблицей ниже: 

Таким образом, API-ключ обычно подходит для идентификации приложения, а токен доступа — для предоставления доступа к ресурсам в пределах выданных разрешений.

Какие бывают виды API-ключей

Можно выделить несколько распространенных категорий API-ключей.

• Ограниченные API-ключи — такие ключи можно использовать только для обращения к определенным функциям API или выполнения конкретных действий. Например, для ключа можно разрешить только чтение данных, запретив их изменение. Даже если ключ будет скомпрометирован, злоумышленник не получит больше прав, чем предусмотрено настройками этого ключа.

• Статические API-ключи — ключи с фиксированным значением, которые, как правило, редко меняются. Такие ключи могут обладать неограниченным сроком действия и привязываются к конкретному приложению.

Публичные и приватные ключи

• Публичные API-ключи — ключи, которые используются в клиентских приложениях например, в мобильных приложениях, где запросы к API выполняются с устройства пользователя. Публичные ключи не являются секретными.

  В качестве примера публичного ключа можно привести сервис Google Maps API, который допускает использование ключей на стороне браузера для отображения карт. Для публичных ключей следует ограничивать список разрешенных API и устанавливать квоты, если сервис поддерживает такие настройки.

• Приватные API-ключи — ключи, которые используются для действий, которые выполняются на сервере и требуют соблюдения конфиденциальных данных. Они могут использоваться для доступа к платежным данным или данным пользователей. Такие ключи нельзя использовать в мобильных приложениях и публичных репозиториях.

Где и как взять API-ключ для своего приложения

API-ключ обычно создается в личном кабинете или консоли управления облачной платформой. Для его получения необходимо зарегистрировать аккаунт, создать проект или выбрать существующий, а затем перейти в раздел управления API-ключами. В зависимости от сервиса перед созданием ключа может потребоваться создать сервисную учетную запись или назначить необходимые права доступа.

Пошаговая инструкция получения ключа

Рассмотрим получение API-ключей в трех популярных сервисах: Google Cloud Console и OpenAI Platform.

Google Cloud Console

1. Чтобы создать API-ключ в Google Cloud Console, разработчику необходимо авторизоваться в своем аккаунте Google. Затем следует выбрать проект или создать новый.

   В разделе Navigation menu слева сверху необходимо открыть раздел APIs & Services → Credentials:

Меню настроек Google Cloud

2. Для создания ключа используется раздел Create credentials → API key:

Раздел Credentilas для создания API-ключа в настройках Google Cloud

3. Далее можно указать название ключа и настроить ограничения:

Поле Name для наименования API-ключа в Google Cloud

4. В разделе API restrictions разработчик выбирает, к каким API разрешено обращаться с помощью ключа. Параметр Application restrictions позволяет ограничить источники запросов, например разрешить использование ключа только на определенных сайтах или с заданных IP-адресов. Доступные варианты зависят от типа приложения:

Список сервисов для использования API-ключа в Google Cloud

5. Ограничения необходимо настроить до использования ключа. Они снижают риск его использования посторонними, однако это не гарантирует абсолютную защиту от злоупотреблений:

Настройки ограничений для API-ключа в Google Cloud

После проверки настроек необходимо нажать Create. Созданный ключ отобразится на экране. Его следует сохранить в безопасном месте и не публиковать в открытом доступе, если он предназначен для секретного использования:

Окно с сгенерированным токеном в Google Cloud

OpenAI Platform

1. Для создания ключа разработчику необходимо авторизоваться в своем аккаунте на платформе OpenAI. Затем следует выбрать нужный проект и перейти в раздел API Keys:

Раздел API keys для создания ключей в настройках OpenAI Platform

2. Для создания ключа используется кнопка Create new secret key:

Кнопка для создания нового ключа в OpenAI Platform

3. Ключ можно создать для личной учетной записи (You) или сервисного аккаунта (Service account).

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

   Service account key — ключ сервисной учетной записи, предназначенный для взаимодействия приложений. Такой вариант подходит для серверных интеграций, которым не требуется зависимость от личной учетной записи разработчика. 

   После выбора типа ключа необходимо указать его название (Name), выбрать проект (Project) и установить срок действия:

Настройки для API-ключа в OpenAI Platform

4. Далее следует выбрать разрешения (Permissions). Доступны варианты All, Restricted и Read Only. Они определяют, какие операции разрешено выполнять с использованием ключа. Следует выбирать минимальный набор разрешений, необходимый приложению:

Список разрешенных действий для API-ключа в OpenAI Platform

5. После настройки необходимо нажать кнопку Create secret key:

Меню с настройками для API-ключа в OpenAI Platform

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

Окно с сгенерированным ключом в OpenAI Platform

Как правильно хранить и использовать API-ключ

Каждый API-ключ должен быть защищен от посторонних, иметь только необходимые права доступа и использоваться только для конкретных действий

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

• Использовать переменные окружения. API-ключи следует передавать приложению через переменные окружения, а не хранить их в исходном коде сервиса.

• Использовать хранилища секретов. Для хранения ключей в production-среде необходимо использовать специализированное программное обеспечение для централизованного хранения, например HashiCorp Vault или AWS Secrets Manager, которые позволяют управлять секретами и контролировать их доступ.

• Не хранить ключи в системы контроля версий. Хранение API-ключей в git-репозиториях категорически запрещено, включая приватные репозитории. При локальной разработки можно использовать .env-файлы, а значения загружать при помощи сторонних библиотек, например dotenv для Python и Node.js.

• Контролировать утечки ключей. В git-репозиториях необходимо использовать механизмы обнаружения секретов, например для GitHub существует сервис GitHub Secret Scanning. Также можно использовать сторонние утилиты вроде TruffleHog и Betterleaks. Если в репозитории обнаружен секрет, его необходимо отозвать или заменить.

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

Частые ошибки при хранении ключей

При работе с API-ключами увеличиваются риски безопасности связанные с их неправильным хранением. При утечке ключей злоумышленник может выполнять запросы от имени приложения, использовать платные функции API, получать доступ к пользовательским данным. Наиболее частые ошибки связаны с публикацией секретов в исходном коде приложения, публикацией в git-репозиториях и передачей по незащищенным каналам.

1. Хранение ключей в исходном коде. Если API-ключ был «зашит» в исходный код приложения, то это упрощает его раскрытие. Ключи могут попасть в сборку приложения, отображаются в журналах и логах. Даже если значения были удалены из файлов, оно все равно может сохраниться в истории коммитов. Ключи следует хранить отдельно от кода — использовать переменные окружения или программы для хранения секретов.

2. Передача ключей по незащищенным каналам. Отправка ключей по электронной почте или в мессенджерах повышает риск их компрометации. Если ключ необходимо передать другому пользователю, следует использовать программные средства для управления секретами с контролем доступа.

3. Избыточные права доступа. Ключ с максимальными правами увеличивает потенциальный ущерб при утечке. Дополнительный риск возникает при отсутствии контроля журналов запросов и расхода квот. Для снижения поверхности атаки необходимо предоставлять ключам только минимально необходимые права и регулярно проверять использование секретов.

Что делать, если ключ скомпрометирован

Если API-ключ был скомпрометирован, необходимо как можно быстрее отозвать его. Важно соблюдать последовательный алгоритм действий: отозвать скомпрометированный ключ, выпустить новый ключ, обновить конфигурацию приложения и проверить его работоспособность. Порядок действий при компрометации ключа следующий:

1. Отозвать скомпрометированный ключ. Старый ключ необходимо отозвать через панель управления. Это предотвратит дальнейшее несанкционированное использование данных.

2. Выпустить новый API-ключ. Создать новый ключ в панели управления сервисом. Выдать ключу только минимально необходимые разрешения. При необходимости ограничить использование ключа конкретным сервисом или приложением.

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

4. Проверить наличие подозрительной активности. Для поиска любой подозрительной активности нужно проверить журналы запросов, историю использования ключа. Стоит искать сведения о подозрительных IP-адресах и действиях. Для этого можно использовать сторонние средства мониторинга, например Datadog.

5. Устранить первоначальную причину утечки. Определить, как ключ оказался доступен посторонним: был ли он опубликован в репозитории, включен в логи, передан через незащищенный канал связи. Удалить секрет из доступных источников, настроить безопасное хранение, проверить разрешения. 

6. Внедрить регулярную ротацию API-ключей. Установить внутреннюю политику замены ключей с учетом требований API-провайдера, уровня риска и характера доступа.

Заключение

API-ключ — это инструмент для идентификации приложения при взаимодействии с программными интерфейсами, который помогает контролировать доступ к ресурсам. Получить ключ можно в панели управления соответствующего сервиса. Безопасность ключей зависит от корректной настройки разрешений, защищенного хранения и своевременной ротации. Организациям рекомендуется провести аудит текущих проектов на предмет небезопасного хранения ключей, поиска в исходном коде и репозиториях, а также проверить настройки доступа.

Часто задаваемые вопросы

1. Что такое API-ключ простыми словами?
API-ключ — это уникальная строка символов, по которой сервис может определить приложение, отправляющее запросы к его программному интерфейсу. Его можно сравнить с идентификатором, предъявляемым при обращении к определенному ресурсу.

2. Зачем нужен API-ключ?
API-ключ помогает сервису идентифицировать приложение и контролировать его обращения к API. С его помощью можно отслеживать количество запросов, ограничивать доступ к определенным функциям и отслеживать использование ресурсов.

3. Как получить API-ключ?
API-ключ обычно в личном кабинете разработчика или консоли управления провайдера. Необходимо зарегистрировать учетную запись и создать проект. После этого следует установить права доступа и сохранить ключ в безопасном месте.

4. Как использовать API-ключ?
API-ключ передается вместе с запросом к API. Обычно ключ указывается в HTTP-заголовке, но также некоторые сервисы допускают передачу в параметрах запроса. Сервер проверяет полученное значение и применяет правила доступа.

5. Как безопасно хранить API-ключ?
API-ключи следует хранить в переменных окружения или специализированных программах для управления секретами. Ключи нельзя публиковать в репозиториях и добавлять в исходный код. Также необходимо ограничивать разрешения и своевременно заменять раскрытые ключи.