API-Schlüssel vs. JWT vs. OAuth2: Wählen Sie die richtige Authentifizierung für Ihre API

Sie erstellen eine API. Die Endpunkte funktionieren. Die Daten fließen. Jetzt müssen Sie eine beantworten Frage vor dem Versand: Wie beweisen Anrufer, wer sie sind?

Drei Ansätze dominieren die API-Authentifizierung: API-Schlüssel, JWTs und OAuth2. Jeder löst a anderes Problem. Wählen Sie die falsche Lösung, und Sie werden entweder eine einfache Integration überdimensionieren oder eine Sicherheitslücke in einem komplexen System hinterlassen.

Dieser Leitfaden vergleicht alle drei anhand von sieben Kriterien, mit funktionierenden Codebeispielen, einer Entscheidung Tabelle und klare Empfehlungen basierend auf dem Anwendungsfall Ihrer API.

API-Schlüsselauthentifizierung: der direkte Ansatz

Ein API-Schlüssel ist eine lange Zufallszeichenfolge, die den Aufrufer identifiziert und autorisiert. Der Kunde sendet Bei jeder Anfrage sucht der Server danach, und wenn er mit einem gültigen Schlüssel übereinstimmt, wird die Anfrage gesendet geht durch.

So sieht ein API-Schlüsselaufruf mit der Botoi-API aus:

# 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"}'

Antwort:

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

Der x-api-key Der Header trägt den Berechtigungsnachweis. Keine auszuhandelnden Token, keine Weiterleitungen, keine Autorisierungsserver. Ein Header, eine Suche, eine Antwort.

Wenn API-Schlüssel gewinnen

• Server-zu-Server-Aufrufe. Ihr Backend ruft ein anderes Backend auf. Kein Benutzer ist beteiligt. Ein Cron-Job fragt eine IP-Geolocation-API ab. Eine CI-Pipeline führt DNS-Prüfungen durch. Der Anrufer ist immer ein vertrauenswürdiger Server.
• Dienstprogramm-APIs. APIs, die zustandslose Operationen ausführen (Hashing, Codierung, Validierung, Nachschlagen), wobei jede Anfrage unabhängig ist. botoi verwendet aus diesem Grund API-Schlüssel: Über 150 Endpunkte, alle zustandslos, alle Server-zu-Server.
• Schnelle Integration. Ein Entwickler kopiert den Schlüssel, fügt einen Header hinzu und beginnt anrufen. Kein OAuth-Tanz, keine Token-Aktualisierungslogik, kein zu konfigurierender JWKS-Endpunkt.

Hier ist der gleiche Aufruf in 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..."

Wo API-Schlüssel unzureichend sind

• Keine Benutzeridentität. Ein API-Schlüssel identifiziert das Konto, nicht den Benutzer. Wenn Drei Entwickler teilen sich einen Schlüssel, man kann nicht sagen, wer welche Anfrage gestellt hat.
• Der Widerruf erfordert einen Hin- und Rückweg. Das Widerrufen eines Schlüssels bedeutet, dass der Server aktualisiert wird Schlüsselspeicher. Bis der Cache aktualisiert wird, funktioniert der alte Schlüssel weiterhin.
• Kein delegierter Zugriff. Sie können eine Drittanbieter-App nicht zeitlich begrenzt und vorübergehend bereitstellen Zugriff auf die Ressourcen eines Benutzers allein mit einem API-Schlüssel.

JWT-Authentifizierung: zustandslose Benutzersitzungen

Ein JSON Web Token (JWT) ist ein signiertes JSON-Objekt, das Ansprüche über den Aufrufer enthält. Der Autor Der Server erstellt es beim Anmelden. der Kunde sendet es mit jeder Anfrage; der Ressourcenserver überprüft die Signatur, ohne den Authentifizierungsserver erneut anzurufen.

// 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
)

Der Server überprüft die Signatur mit dem öffentlichen Schlüssel. Wenn die Signatur auscheckt und exp nicht bestanden wurde, ist die Anfrage autorisiert. Keine Datenbanksuche erforderlich.

Wenn JWTs gewinnen

• Benutzerorientierte APIs mit hohem Datenverkehr. Eine mobile App sendet bei jedem ein JWT Anfrage. Das API-Gateway überprüft die Signatur lokal, anstatt einen Sitzungsspeicher abzufragen bei jedem Anruf. Bei 10.000 Anfragen pro Sekunde ist der von Ihnen übersprungene Datenbankaufruf von Bedeutung.
• Microservice-Architekturen. Dienst A ruft Dienst B mit einem JWT auf. Dienst B validiert es lokal und extrahiert die Benutzer-ID und Rollen aus den Ansprüchen. Keine gemeinsame Sitzung Datenbank zwischen Diensten.
• Kurzfristige Genehmigung. Ein 15-Minuten-Token für einen Datei-Upload. Eine 5-minütige Token für eine Zahlungsbestätigung. Der Ablauf ist in den Token selbst integriert.

Hier ist Express-Middleware, die ein JWT überprüft:

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" });
  }
}

Wo JWTs zu kurz kommen

• Der Widerruf eines Tokens ist schwierig. Ein JWT ist gültig, bis es abläuft. Wenn sich ein Benutzer anmeldet aus oder Sie müssen den Zugriff widerrufen, benötigen Sie eine serverseitige Sperrliste, die den zurückbringt Datenbankaufruf, den Sie vermeiden wollten.
• Nutzlastgröße. Jeder Anspruch fügt Bytes hinzu. Ein JWT mit Benutzerrollen, Berechtigungen, und Metadaten können 1-2 KB erreichen. Das sind 1–2 KB bei jeder einzelnen Anfrage und in jedem Header.
• Komplexität der Schlüsselrotation. Wenn Sie Signaturschlüssel rotieren, werden alte Token signiert mit dem bisherigen Schlüssel müssen bis zum Ablauf gültig bleiben. Das bedeutet, mehrere zu bedienen öffentliche Schlüssel über einen JWKS-Endpunkt und Handhabung der kid Header-Anspruch.

OAuth2: delegierter Zugriff für Dritte

OAuth2 ist ein Autorisierungsframework, kein Authentifizierungsprotokoll. Es ermöglicht einem Benutzer, eine zu gewähren Drittanbieteranwendungen beschränken den Zugriff auf ihre Ressourcen auf einem anderen Dienst, ohne sie zu teilen ihr Passwort.

Das klassische Beispiel: Ein Benutzer autorisiert ein Projektmanagement-Tool, seinen GitHub zu lesen Repositories. Der Benutzer meldet sich bei GitHub an, genehmigt bestimmte Bereiche und das Tool erhält eine Zugriffstoken, das auf diese Berechtigungen beschränkt ist.

# 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

Wenn OAuth2 gewinnt

• Integrationen von Drittanbietern. Sie betreiben eine Plattform und möchten externe Entwickler um Apps zu erstellen, die auf die Daten Ihrer Benutzer zugreifen. OAuth2 gibt Benutzern die Kontrolle über die einzelnen Apps zugreifen kann.
• Feinkörnige Bereiche. read:repos aber nicht delete:repos. write:issues aber nicht admin:org. OAuth2 Mit Bereichen können Benutzer bestimmte Berechtigungen genehmigen.
• „Mit X anmelden“ fließt. Wenn Ihre App Google, GitHub oder Microsoft verwendet Wenn Sie sich anmelden, verwenden Sie OAuth2 (häufig mit OpenID Connect zusätzlich), um ein Identitätstoken zu erhalten.

Wo OAuth2 zu kurz kommt

• Komplexität. OAuth2 verfügt über vier Gewährungstypen: Aktualisierungstoken und Autorisierung Server, Umleitungs-URIs, PKCE und Token-Introspektion-Endpunkte. Für eine Utility-API mit Kein Benutzerkontext, dies ist ein Overhead ohne Nutzen.
• Integrationsreibung. Ein Entwickler, der Ihren Hash-Endpunkt aufrufen möchte möchte keine OAuth-App registrieren, Umleitungs-URIs einrichten und keine Autorisierung austauschen Codes. Sie wollen einen Schlüssel und einen Curl-Befehl.
• Belastung durch Token-Verwaltung. Zugriffstokens laufen ab. Aktualisierungstoken rotieren. Clients benötigen eine Wiederholungslogik für 401-Antworten. Für einfache Server-zu-Server-Aufrufe ist dies der Fall unnötige Maschinen.

Vergleichstabelle

Kriterien	API-Schlüssel	JWT	OAuth2
Integrationszeit	Minuten	Std	Tage
Benutzeridentität	Kontoebene	Benutzerebene (Ansprüche)	Benutzerebene (Bereiche)
Staatenlose Verifizierung	Nein (Serversuche)	Ja (Signaturprüfung)	Hängt vom Tokenformat ab
Widerrufsgeschwindigkeit	Sofort (Taste löschen)	Verzögert (bis zum Ablauf)	Sofort (Token widerrufen)
Delegierter Zugriff	NEIN	NEIN	Ja
Unterstützung durch Dritte	Arm	Gut	Exzellent
Geeignet für Browser	Nein (Hauptbelichtung)	Ja (von kurzer Dauer)	Ja (Autorisierungscode + PKCE)

Entscheidungsrahmen: Wählen Sie basierend auf Ihrem Anwendungsfall aus

Hören Sie auf zu fragen: „Was ist am sichersten?“ Bei richtiger Anwendung sind alle drei sicher. Das Richtige Frage: „Wer ruft meine API auf und warum?“

• Server ruft Server auf, kein Benutzer beteiligt: API-Schlüssel. Ihr Backend ruft a auf Dienstprogramm-API für DNS-Suchen, Hashing oder Datenvalidierung. Ein Schlüssel, ein Header, fertig.
• Ihre eigene App authentifiziert Ihre eigenen Benutzer: JWT. Ihre mobile App oder Ihr SPA sendet Anfragen im Namen eines angemeldeten Benutzers. Signieren Sie beim Anmelden ein kurzlebiges JWT und überprüfen Sie es bei jeder Anfrage ohne Sitzungsspeicher.
• Drittanbieter-Apps greifen auf Benutzerdaten zu: OAuth2. Externe Entwickler bauen Integrationen mit Ihrer Plattform. Benutzer steuern über den Gültigkeitsbereich, worauf jede App zugreifen kann Einwilligungsbildschirme.

API-Schlüssel im großen Maßstab mit Unkey verwalten

API-Schlüssel klingen einfach, bis Sie sie hashen, Ratenbeschränkungen durchsetzen und das Ablaufdatum festlegen müssen Daten, verfolgen Sie die Nutzung pro Schlüssel und rotieren Sie sie ohne Ausfallzeiten. Bauen Sie das alles auf Ein Kratzer dauert Wochen.

Unschlüsselbar ist eine offene Quell-API-Schlüsselverwaltungsdienst, der die Erstellung, Überprüfung, Ratenbegrenzung usw. übernimmt Analytik. botoi verwendet Unkey, um alle API-Schlüssel auf seinen über 150 Endpunkten zu verwalten.

Erstellen Sie einen bereichsbezogenen Schlüssel mit integrierter Ratenbegrenzung:

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..."

Überprüfen Sie es in Ihrer Middleware:

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 speichert Schlüssel gehasht (niemals im Klartext), erzwingt Ratenbegrenzungen am Rand und gibt Sie erhalten ein Analyse-Dashboard, das die Nutzung pro Schlüssel anzeigt. Wenn ein Schlüssel gedreht werden muss, erstellen Sie einen neuen und legen Sie ein Ablaufdatum für das alte fest. Keine Ausfallzeiten, keine Codeänderungen.

Sicherheitscheckliste für jeden Ansatz

API-Schlüssel

• Nur über HTTPS senden. Betten Sie niemals Schlüssel in URLs oder Abfragezeichenfolgen ein.
• Gehasht auf dem Server speichern. Protokollieren Sie niemals rohe Schlüssel.
• Bereichsschlüssel für bestimmte Berechtigungen (schreibgeschützt, schreiben, admin).
• Ablaufdaten festlegen. Erzwingen Sie eine Rotation alle 90 Tage.
• Verwenden Sie einen benutzerdefinierten Header (x-api-key) anstatt Authorization zu Vermeiden Sie das Zwischenspeichern von Browser-Anmeldeinformationen.

JWTs

• Verwenden Sie asymmetrische Signatur (RS256 oder ES256). Verwenden Sie niemals HS256 mit einem gemeinsamen Geheimnis Verteilte Systeme.
• Halten Sie die Lebensdauer des Tokens kurz: 5–15 Minuten für Zugriffstoken.
• Bestätigen iss, aud, Und exp Ansprüche auf jeden Anfrage.
• Öffentliche Schlüssel über einen JWKS-Endpunkt veröffentlichen. Signierschlüssel nach einem Zeitplan rotieren.
• Speichern Sie niemals sensible Daten in der Nutzlast. JWTs sind codiert, nicht verschlüsselt.

OAuth2

• Verwenden Sie den Autorisierungscode-Flow mit PKCE für alle Clients, einschließlich SPAs und Mobilgeräte Apps.
• Verwenden Sie niemals den impliziten Fluss. Es ist in OAuth 2.1 aus gutem Grund veraltet.
• Speichern Sie Client-Geheimnisse nur auf dem Server. Versenden Sie sie niemals in mobilen Apps oder im Frontend Code.
• Bestätigen state Parameter, um CSRF-Angriffe auf die Rückruf-URL zu verhindern.
• Verwenden Sie kurzlebige Zugriffstoken mit Aktualisierungstokenrotation.

Wichtige Punkte

• API-Schlüssel sind die richtige Wahl für Server-zu-Server-Dienstprogramm-APIs. Das sind sie schnell zu integrieren, einfach zu verwalten und ausreichend, wenn keine Benutzeridentität erforderlich ist. botoi verwendet sie auf über 150 Endpunkten mit Unkey für die Verwaltung.
• JWTs sind die richtige Wahl für zustandslose Benutzersitzungen. Sie beseitigen Sitzungsspeichersuchen in großem Umfang, aber der Token-Widerruf erfordert zusätzliche Infrastruktur.
• OAuth2 ist die richtige Wahl, wenn Drittanbieter-Apps einen eingeschränkten Zugriff benötigen Benutzerressourcen. Die Komplexität wird durch das bereitgestellte Sicherheitsmodell gerechtfertigt.
• Wählen Sie basierend auf dem Anrufer aus, nicht auf dem Hype. Eine Dienstprogramm-API mit OAuth2 ist überentwickelt. A Plattform-API mit nur API-Schlüsseln kann keinen delegierten Zugriff gewähren.
• Kombinieren Sie Ansätze, wenn Ihr Produkt es erfordert. API-Schlüssel für direkte Integrationen, OAuth2 für Marktplatzpartner, JWTs für angemeldete Benutzersitzungen.