Lern-Motor

Das Cockpit lebt von Daten, die es nicht selbst hat: Umsätze, Quoten, Kampagnen. Die holt es über eine API — und der Schlüssel dafür ist das Wertvollste am ganzen Projekt. Diese Lektion zeigt beides: wie so ein Gespräch mit einer API abläuft, und wo der Schlüssel wohnt, damit ihn niemand mitliest.

Anatomie eines Requests

So sieht das Gespräch aus, das dein Server später mit der Reporting-API führt:

curl -s "https://api.beispiel.dev/v1/reports/kampagnen" \
  -H "Authorization: Bearer key_beispiel123" \
  -H "User-Agent: mein-cockpit/1.0"

Vier Teile, mehr ist es nicht:

Adresse: api.beispiel.dev ist der Server, /v1/reports/kampagnen der Endpunkt — eine Tür für genau eine Sache. Das v1 ist die Version: Ändert sich die API grundlegend, gibt es eine v2, und dein Code läuft an der alten Tür weiter.
Methode: GET heißt lesen, POST heißt anlegen oder senden. Ein Reporting-Key liest nur.
Kopfzeilen (Header): Metadaten zum Request. Authorization: Bearer … ist der Ausweis. User-Agent sagt, wer da anklopft — manche Server lassen anonyme Anfragen gar nicht erst durch.
Antwort: JSON plus ein dreistelliger Statuscode, der sagt, wie es lief.

„Bearer" heißt wörtlich Inhaber: Wer diesen Header vorzeigen kann, ist du. Kein Passwort dahinter, keine zweite Stufe. Das erklärt die ganze zweite Hälfte dieser Lektion.

Probieren: der Request-Bauer

Bau den Request selbst zusammen. Die API hier ist simuliert, verhält sich aber wie das Original — inklusive der Wache, die vor manchen APIs steht und anonyme Anfragen abweist, bevor die API sie überhaupt sieht.

Reporting-API · simuliert

Methode

Endpunkt

Header

GET https://api.beispiel.dev/v1
(keine Header gesetzt)

Noch nichts gesendet.

Probier bewusst auch die falschen Kombinationen — die Fehlermeldungen sind der Lernstoff.

Was du dabei siehst, sind die drei Antworten, die dir draußen ständig begegnen: 401 heißt „kein gültiger Ausweis" — der Bearer-Header fehlt oder stimmt nicht. 403 heißt „Ausweis ok, trotzdem nicht" — hier, weil die Wache vor der API (ein sogenanntes Edge, oft Cloudflare) Anfragen ohne User-Agent abblockt; die Fehlermeldung kommt dann gar nicht von der API selbst. Und 200 heißt: Daten da.

Ordne jedem Statuscode seine Bedeutung zu.

0 von 5 zugeordnet

Der Tresor: .env

Der Key steht nie im Code. Er steht in einer Datei namens .env.local im Projektordner — und die bleibt auf deinem Rechner:

# .env.local
BRAIN_API_KEY=key_beispiel123
COCKPIT_PASSWORT=ein-langes-passwort

Im Server-Code liest du ihn mit process.env.BRAIN_API_KEY. Drei Dinge dazu, die man leicht falsch im Kopf hat:

Git nimmt die Datei nicht mit. create-next-app trägt .env* in die .gitignore ein. Das heißt aber auch: Willst du eine .env.example (die leere Vorlage, die zeigt, welche Variablen das Projekt braucht) committen, musst du sie ausdrücklich freischalten — eine Zeile !.env.example in der .gitignore.
Der Dev-Server merkt Änderungen von selbst. Änderst du .env.local, während npm run dev läuft, lädt Next die Datei neu (im Terminal steht dann Reload env). Anders beim deployten Projekt: Dort trägst du die Variablen im Hosting-Interface ein, und eine Änderung greift erst mit dem nächsten Deploy.
Die NEXT_PUBLIC_-Falle: Variablen mit diesem Präfix baut Next in den Browser-Code ein — sie sind öffentlich. Für Keys also nie. Schlägt dir eine AI NEXT_PUBLIC_BRAIN_API_KEY vor: ablehnen, serverseitig lösen lassen.

Du hast einen API-Key aus Versehen in einen Team-Chat gepostet und die Nachricht gleich gelöscht. Was gilt?

Alles zusammen: der Weg des Keys

Noch einmal die drei Ebenen aus der ersten Lektion, jetzt mit dem Key eingezeichnet: Der Browser fragt deinen Server — ohne Key. Dein Server liest den Key aus process.env, hängt ihn als Bearer-Header an und fragt die API. Die Antwort geht ohne Key zurück an den Browser. Der Key überquert die Grenze zur Ebene 1 nie.

Der Beweis-Test nach jedem Deploy dauert zehn Sekunden: Seite öffnen, Quelltext anzeigen (Cmd+U), nach dem Anfang deines Keys suchen — null Treffer, sonst ist etwas falsch verdrahtet.

Dein deploytes Cockpit zeigt plötzlich überall Striche, im Server-Log steht 401 von der Reporting-API. Wo suchst du zuerst?

Sitzt das?

Häufige Fragen

Warum reicht HTTPS nicht als Schutz für den Key?

HTTPS verschlüsselt den Transportweg — niemand kann unterwegs mitlesen. Aber es ändert nichts daran, wer die Nachricht bekommt: Liegt der Key im Seitencode, liefert HTTPS ihn sicher verschlüsselt an jeden Betrachter aus.

Was ist mit den Meta- und Google-Ads-APIs?

Die laufen nicht über einen einfachen Bearer-Key, sondern über OAuth: Tokens, die nach kurzer Zeit ablaufen und serverseitig erneuert werden müssen. Genau dafür braucht es die Server-Ebene — im Browser ist das nicht machbar. Der Umbau jetzt ist die Voraussetzung dafür.

Woher weiß ich, welche Endpunkte eine API hat?

Aus ihrer Dokumentation — jede ernsthafte API hat eine. Dort stehen Endpunkte, Parameter und Beispielantworten. Die liest man nicht auswendig, man schlägt nach.