Ключ API против JWT против OAuth2: выберите правильную аутентификацию для вашего API

Вы создаете API. Конечные точки работают. Данные текут. Теперь вам нужно ответить на один вопрос перед отправкой: как звонящие доказывают, кто они?

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

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

Аутентификация по ключу API: прямой подход

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

Вот как выглядит вызов ключа API с помощью API botoi:

# API key in a custom header
curl -s -X POST https://api.botoi.com/v1/dns/lookup \\
  -H "Content-Type: application/json" \\
  -H "x-api-key: your_api_key_here" \\
  -d '{"domain": "example.com", "type": "A"}'

Ответ:

{
  "success": true,
  "data": {
    "domain": "example.com",
    "type": "A",
    "records": [
      { "type": "A", "value": "93.184.216.34", "ttl": 86400 }
    ]
  }
}

The x-api-key заголовок содержит учетные данные. Никаких токенов для согласования, никаких перенаправлений, нет серверов авторизации. Один заголовок, один поиск, один ответ.

Когда ключи API выигрывают

• Межсерверные вызовы. Ваш бэкэнд вызывает другой бэкэнд. Ни один пользователь не участвует. Задание cron запрашивает API геолокации IP. Конвейер CI выполняет проверки DNS. Звонящий всегда является доверенным сервером.
• API-интерфейсы утилит. API, выполняющие операции без сохранения состояния (хеширование, кодирование, проверка, поиск), где каждый запрос независим. botoi использует ключи API по этой причине: Более 150 конечных точек, все без сохранения состояния, все между серверами.
• Быстрая интеграция. Разработчик копирует ключ, добавляет один заголовок и начинает звоню. Никакого танца OAuth, никакой логики обновления токена, никакой конечной точки JWKS, которую нужно настроить.

Вот тот же вызов в Node.js:

const response = await fetch("https://api.botoi.com/v1/hash", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BOTOI_API_KEY,
  },
  body: JSON.stringify({ text: "hello world", algorithm: "sha256" }),
});

const result = await response.json();
// result.data.hash = "b94d27b9934d3e08..."

Где ключи API терпят неудачу

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

Аутентификация JWT: сеансы пользователей без сохранения состояния

Веб-токен JSON (JWT) — это подписанный объект JSON, содержащий утверждения о вызывающей стороне. Авторизация сервер создает его при входе в систему; клиент отправляет его с каждым запросом; сервер ресурсов проверяет подпись без повторного вызова сервера аутентификации.

// Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "user_12345",
  "email": "dev@example.com",
  "role": "admin",
  "iat": 1775000000,
  "exp": 1775000900   // 15 minutes
}

// Signature
RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  privateKey
)

Сервер проверяет подпись с помощью открытого ключа. Если подпись проверена и exp не прошло, запрос авторизован. Никакого поиска в базе данных не требуется.

Когда JWT побеждают

• Пользовательские API с высоким трафиком. Мобильное приложение отправляет JWT каждый раз. запрос. Шлюз API проверяет подпись локально, а не запрашивает хранилище сеансов. при каждом звонке. При 10 000 запросов в секунду тот вызов базы данных, который вы пропустили, имеет значение.
• Микросервисные архитектуры. Служба A вызывает службу B с помощью JWT. Услуга Б проверяет его локально и извлекает идентификатор пользователя и роли из утверждений. Нет общего сеанса база данных между сервисами.
• Краткосрочная авторизация. 15-минутный токен на загрузку файла. 5 минут токен для подтверждения платежа. Срок действия встроен в сам токен.

Вот промежуточное программное обеспечение Express, которое проверяет JWT:

import jwt from "jsonwebtoken";

function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ error: "Missing token" });

  try {
    const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY, {
      algorithms: ["RS256"],
    });
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(401).json({ error: "Invalid or expired token" });
  }
}

Где JWT терпят неудачу

• Отозвать токен сложно. JWT действителен до истечения срока его действия. Если пользователь входит в систему или вам нужно отозвать доступ, вам нужен черный список на стороне сервера, который возвращает вызов базы данных, которого вы пытались избежать.
• Размер полезной нагрузки. Каждое утверждение добавляет байты. JWT с ролями пользователей, разрешениями, а метаданные могут достигать 1-2 КБ. Это 1-2 КБ на каждый запрос, в каждом заголовке.
• Сложность вращения ключей. При ротации ключей подписи старые токены подписываются. с предыдущим ключом, должны оставаться действительными до истечения срока их действия. Это означает обслуживание нескольких открытые ключи через конечную точку JWKS и обработку kid претензия в заголовке.

OAuth2: делегированный доступ для третьих лиц

OAuth2 — это платформа авторизации, а не протокол аутентификации. Это позволяет пользователю предоставить стороннее приложение ограничило доступ к своим ресурсам на другом сервисе, не разделяя их пароль.

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

# Step 1: Redirect user to authorization server
GET https://auth.example.com/authorize?
  response_type=code&
  client_id=your_app_id&
  redirect_uri=https://yourapp.com/callback&
  scope=read:repos+write:issues&
  state=random_csrf_token

# Step 2: Exchange authorization code for tokens
POST https://auth.example.com/token
  grant_type=authorization_code&
  code=AUTH_CODE_FROM_CALLBACK&
  client_id=your_app_id&
  client_secret=your_app_secret&
  redirect_uri=https://yourapp.com/callback

# Step 3: Call the API with the access token
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \\
  https://api.example.com/v1/repos

Когда OAuth2 побеждает

• Сторонние интеграции. У вас есть платформа и вам нужны внешние разработчики для создания приложений, которые получают доступ к данным ваших пользователей. OAuth2 дает пользователям контроль над тем, что каждое приложение может получить доступ.
• Мелкозернистые области видимости. read:repos но не delete:repos. write:issues но не admin:org. ОАут2 области позволяют пользователям утверждать определенные разрешения.
• «Войти с помощью X» выполняется. Если ваше приложение использует Google, GitHub или Microsoft для при входе в систему вы используете OAuth2 (часто с OpenID Connect сверху) для получения токена идентификации.

Где OAuth2 терпит неудачу

• Сложность. OAuth2 имеет четыре типа предоставления, токены обновления, авторизацию. серверы, URI перенаправления, PKCE и конечные точки самоанализа токенов. Для служебного API с нет пользовательского контекста, это накладные расходы, не приносящие никакой пользы.
• Интеграционное трение. Разработчик, который хочет позвонить в вашу конечную точку хэша. не хочет регистрировать приложение OAuth, настраивать URI перенаправления и обмениваться авторизацией коды. Им нужен ключ и команда curl.
• Бремя управления токенами. Срок действия токенов доступа истекает. Токены обновления вращаются. Клиентам необходима логика повтора для ответов 401. Для простых вызовов между серверами это ненужная техника.

Сравнительная таблица

Критерии	API-ключ	JWT	ОАут2
Время интеграции	Минуты	Часы	Дни
Личность пользователя	На уровне аккаунта	Уровень пользователя (претензии)	Уровень пользователя (области действия)
Проверка без гражданства	Нет (поиск сервера)	Да (проверка подписи)	Зависит от формата токена
Скорость отзыва	Немедленно (удалить ключ)	Отложено (до истечения срока действия)	Немедленно (отзыв токена)
Делегированный доступ	Нет	Нет	Да
Сторонняя поддержка	Бедный	Хороший	Отличный
Подходит для браузеров	Нет (ключевое воздействие)	Да (недолговечный)	Да (код авторизации + PKCE)

Схема принятия решений: выбирайте в зависимости от вашего варианта использования

Перестаньте спрашивать: «Что наиболее безопасно?» Все три безопасны при правильном использовании. Право вопрос: «кто вызывает мой API и почему?»

• Сервер вызывает сервер, пользователь не участвует: API-ключ. Ваш бэкэнд вызывает служебный API для поиска DNS, хеширования или проверки данных. Один ключ, один заголовок, готово.
• Ваше собственное приложение аутентифицирует ваших пользователей: ДЖВТ. Ваше мобильное приложение или SPA отправляет запросы от имени вошедшего в систему пользователя. Подпишите недолговечный JWT при входе в систему, проверьте его. по каждому запросу без хранилища сеансов.
• Сторонние приложения получают доступ к пользовательским данным: ОАут2. Внешние разработчики создают интеграция с вашей платформой. Пользователи контролируют, к чему каждое приложение может получить доступ через ограниченную область действия. экраны согласия.

Управление ключами API в любом масштабе с помощью Unkey

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

Неключевой является открытым Служба управления ключами исходного API, которая занимается созданием, проверкой, ограничением скорости и аналитика. botoi использует Unkey для управления всеми ключами API на своих более чем 150 конечных точках.

Создайте ключ с областью действия со встроенным ограничением скорости:

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });

// Create a scoped API key with built-in rate limiting
const key = await unkey.keys.create({
  apiId: "api_your_api_id",
  prefix: "botoi",
  meta: { userId: "user_12345", plan: "pro" },
  expires: Date.now() + 90 * 24 * 60 * 60 * 1000, // 90 days
  ratelimit: {
    type: "fast",
    limit: 100,
    refillRate: 10,
    refillInterval: 1000,
  },
});

// key.result.key = "botoi_3xK9m2..."

Проверьте это в своем промежуточном программном обеспечении:

import { verifyKey } from "@unkey/api";

async function authMiddleware(req, res, next) {
  const apiKey = req.headers["x-api-key"];
  if (!apiKey) return res.status(401).json({ error: "Missing API key" });

  const result = await verifyKey(apiKey);

  if (!result.result.valid) {
    return res.status(result.result.code === "RATE_LIMITED" ? 429 : 403)
      .json({ error: result.result.code });
  }

  req.keyMeta = result.result.meta; // { userId, plan }
  next();
}

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

Контрольный список безопасности для каждого подхода

Ключи API

• Отправляйте только через HTTPS. Никогда не встраивайте ключи в URL-адреса или строки запроса.
• Храните хешированные на сервере. Никогда не регистрируйте необработанные ключи.
• Назначьте ключам определенные разрешения (только чтение, запись, администратор).
• Установите сроки годности. Ротация сил каждые 90 дней.
• Используйте собственный заголовок (x-api-key) вместо Authorization чтобы избегайте кэширования учетных данных браузера.

JWT

• Используйте асимметричную подпись (RS256 или ES256). Никогда не используйте HS256 с общим секретом в распределенные системы.
• Срок действия токена должен быть коротким: 5–15 минут для токенов доступа.
• Подтвердить iss, aud, и exp претензии по каждому запрос.
• Публикуйте открытые ключи через конечную точку JWKS. Меняйте ключи подписи по расписанию.
• Никогда не храните конфиденциальные данные в полезной нагрузке. JWT закодированы, а не зашифрованы.

ОАут2

• Используйте поток кода авторизации с PKCE для всех клиентов, включая SPA и мобильные устройства. приложения.
• Никогда не используйте неявный поток. В OAuth 2.1 он устарел по уважительной причине.
• Храните секреты клиента только на сервере. Никогда не добавляйте их в мобильные приложения или интерфейс. код.
• Подтвердить state параметры для предотвращения атак CSRF на URL-адрес обратного вызова.
• Используйте кратковременные токены доступа с ротацией токенов обновления.

Ключевые моменты

• Ключи API являются правильным выбором для API-интерфейсов межсерверных утилит. Они быстро интегрируется, прост в управлении и достаточен, когда личность пользователя не требуется. ботой использует их на более чем 150 конечных точках с помощью Unkey для управления.
• JWT являются правильным выбором для пользовательских сеансов без сохранения состояния. Они устраняют поиск в хранилище сеансов в больших масштабах, но для отзыва токенов требуется дополнительная инфраструктура.
• ОАут2 является правильным выбором, когда сторонним приложениям требуется ограниченный доступ к ресурсы пользователя. Сложность оправдана моделью безопасности, которую она обеспечивает.
• Выбирайте, основываясь на звонящем, а не на шумихе. Утилитный API с OAuth2 переработан. А API платформы, имеющий только ключи API, не может предоставить делегированный доступ.
• Комбинируйте подходы, когда этого требует ваш продукт. Ключи API для прямой интеграции, OAuth2 для партнеров на рынке — JWT для сеансов вошедших в систему пользователей.