Authentifizierung

Zwei Wege, einen Schlüssel zu senden

Beide Header tragen denselben Schlüssel und beide sind kanonisch: Keiner wird abgeschafft. Sendest du beide, gewinnt X-API-Key. Der Schemaname wird ohne Groß-/Kleinschreibung verglichen.

1curl -H "X-API-Key: your_api_key" \2  https://api.gunspec.io/v1/firearms

1curl -H "Authorization: Bearer your_api_key" \2  https://api.gunspec.io/v1/firearms

Sende einen Schlüssel nur über TLS und nur aus serverseitigem Code; die Seite Sicherheit behandelt die Hygiene.

Was einen Schlüssel braucht

134 Operationen brauchen ein Credential; 30 antworten ohne.

flowchart TD
  start["A request to /v1"] --> has{"API key sent?"}
  has -->|"no"| open{"Open without a key?"}
  open -->|"yes"| handler["Answered"]:::ok
  open -->|"no"| unauth["Refused: 401 API_KEY_MISSING"]:::fail
  has -->|"yes"| valid{"Key valid and in date?"}
  valid -->|"no"| expired["Refused: 401 KEY_EXPIRED"]:::fail
  valid -->|"yes"| account{"Account in good standing?"}
  account -->|"no"| suspended["Refused: 403 ACCOUNT_SUSPENDED"]:::fail
  account -->|"yes"| plan{"Plan covers this endpoint?"}
  plan -->|"no"| upgrade["Refused: 403 PLAN_REQUIRED"]:::fail
  plan -->|"yes"| handler

Was ein Schlüssel freischaltet

Ein Schlüssel trägt seinen Plan. Der Plan entscheidet, welche Endpunkte antworten, wie viele Felder zurückkommen, wie tief eine Liste geblättert werden kann und wie viele Anfragen pro Minute und Tag erlaubt sind.

• ExplorerKostenlos. Die Listen-Endpunkte mit reduziertem Feldsatz, fünf Seiten tief, verborgene Gesamtzahlen.
• BuilderVolle Spezifikationen, Suche, Vergleich, Bild- und 3D-Modell-URLs, Game-Stats.
• StudioJeder Endpunkt inklusive Kompatibilitäts-Engine, Webhooks, unbegrenztes Blättern.
• EnterpriseStudio plus Händlereintrag, die höchsten Limits, ein SLA und dedizierter Support.

Schlüssel erstellen, rotieren und widerrufen

Schlüssel liegen in deinem Profil auf der Hauptseite. Ein Schlüssel wird einmal bei der Erstellung gezeigt; speichere ihn dann.

1. 1Auf gunspec.io anmelden und Profil, dann API-Schlüssel öffnen.
2. 2Einen Schlüssel pro Anwendung oder Umgebung erstellen und so benennen, dass du später weißt, was du widerrufst.
3. 3Planmäßig rotieren: neuen Schlüssel erstellen, ausrollen, dann den alten widerrufen. Der Widerruf wirkt sofort.
4. 4Einen Schlüssel deaktivieren, um ihn zu pausieren, ohne Namen und Verlauf zu verlieren; ein deaktivierter Schlüssel antwortet 401 KEY_DISABLED.

API-Schlüssel im Profil öffnenSchlüsselhygiene

Wenn ein Schlüssel abgelehnt wird

Ein 401 betrifft immer das Credential, und error.reason nennt das Problem. Ein 403 heißt, der Schlüssel ist in Ordnung und Plan oder Konto sind nicht berechtigt; ein neuer Schlüssel ändert daran nichts.

• AUTH_REQUIREDThis endpoint needs a credential and none was sent.
• KEY_MISSINGNo API key was sent.
• KEY_INVALIDThe API key is not one we issued, or it has been deleted.
• KEY_DISABLEDThe key was switched off by the account that owns it.
• KEY_EXPIREDThe key has passed its expiry date.

Im Playground ausprobieren

Jede Endpunktseite hat eine Try-It-Konsole. Einen Schlüssel einmal einfügen; er bleibt nur in diesem Browser, wird bei jeder Anfrage aus der Konsole als X-API-Key gesendet und von uns nie gespeichert.