FirstSales mit Codex verwenden

Verbinden Sie Codex mit FirstSales über die REST-API (oder die CLI in einer Shell) — erster whoami-Aufruf, eingeschränkte Schlüssel, idempotente Schreibvorgänge und Abbruch bei nicht unterstützten Operationen.

8 Min. Lesezeit·Experte·6 Schritte

1
Den richtigen Weg für Ihr Codex-Setup wählen
FirstSales bietet zwei Integrationswege. Wenn Ihre Codex-Umgebung über eine Shell mit npm verfügt, installieren Sie das @firstsales.io/cli und steuern es wie jeden Shell-Agenten — es übernimmt Authentifizierung, JSON und Idempotenz für Sie. Wenn Codex ohne Shell-Zugriff läuft (Browser oder Sandbox), rufen Sie die Developer API direkt über HTTPS auf. Die Dokumentation ordnet Codex genau aus diesem Grund den API-first-Agenten zu.
2
Den Schlüssel als Umgebungs-Secret speichern
Erstellen Sie einen Developer-API-Schlüssel unter Settings → API und legen Sie ihn im Secret Store Ihrer Codex-Umgebung als FIRSTSALES_API_KEY ab. Fügen Sie den rohen Schlüssel niemals in einen Prompt ein und committen Sie ihn nicht — referenzieren Sie die Umgebungsvariable im Code.
```
# in your Codex task's environment
FIRSTSALES_API_KEY=fs-key-...
FIRSTSALES_BASE_URL=https://api.app.firstsales.io
```
3
Zuerst die Identität prüfen
Unabhängig vom gewählten Weg bestätigt der erste Aufruf, dass der Schlüssel zur erwarteten Organisation und zum erwarteten Workspace gehört:
```
curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
```

Vor dem Schreiben den Zustand lesen

Lassen Sie Codex vor jeder Änderung erst prüfen. Ressourcen sind auf Organisation und Workspace beschränkt:

curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/campaigns \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

Idempotent schreiben

Senden Sie bei Erstellungen einen Idempotency-Key-Header, damit eine wiederholte Anfrage niemals Daten dupliziert — wichtig für einen autonomen Agenten, der bei einem Timeout erneut senden kann:

curl -X POST \
  https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: codex-lead-2026-01" \
  -d '{"email":"lead@acme.com","first_name":"Sam"}'

6
Codex auf der öffentlichen Oberfläche halten
Weisen Sie Codex an, ausschließlich öffentliche /api/v1-Endpunkte zu verwenden. Bei einer unsupported_operation-Antwort muss es stoppen und melden — niemals die App scrapen oder private Routen, Provider-Callbacks, Tracking-Pixel, Unsubscribe-Handler oder Cron-Endpunkte aufrufen, um ein Ergebnis zu erzwingen. Behandeln Sie 401 (falscher Schlüssel), 422 (Validierung — der Body nennt das Feld) und 429 (zurückrudern) explizit.

Profi-Tipps

Hart erarbeitete Abkürzungen, damit die Aufwärmung auf Kurs bleibt.

Shell vorhanden? Bevorzugen Sie die CLI

Wenn Ihre Codex-Sandbox npm ausführen kann, nimmt Ihnen die CLI viel Boilerplate ab — Authentifizierung, JSON, Idempotenz und Lösch-Bestätigung werden für Sie erledigt. Greifen Sie nur bei fehlender Shell auf rohes HTTP zurück.

Der Schlüssel gehört in die Umgebung, nicht in den Prompt

Legen Sie FIRSTSALES_API_KEY im Secret Store von Codex ab und referenzieren Sie ihn. Ein Schlüssel im Prompt landet in Logs und Verlauf.

whoami ist der günstigste Sicherheitscheck

Ein einziger Aufruf bestätigt, dass Codex auf die richtige Organisation und den richtigen Workspace zeigt, bevor irgendetwas geschrieben wird. Wer ihn überspringt, riskiert Daten im falschen Workspace.

Idempotency-Key bei jeder Erstellung

Autonome Agenten wiederholen Anfragen. Ein stabiler Idempotenzschlüssel macht aus einem wiederholten POST ein No-op statt eines doppelten Kontakts oder einer doppelten Abbuchung.

Häufig gestellte Fragen

Soll Codex die CLI oder die API verwenden?

Wenn Codex Shell-Zugriff mit npm hat, nutzen Sie die CLI. Läuft es in einem Browser oder einer Sandbox ohne Shell, rufen Sie die Developer API über HTTPS auf. Der API-Weg ist der Standard für browserbasierte Agenten.

Wie übergebe ich Codex den Schlüssel sicher?

Speichern Sie ihn als FIRSTSALES_API_KEY im Umgebungs-/Secret Store von Codex und referenzieren Sie die Variable im Code. Fügen Sie den rohen Schlüssel nicht in Prompts ein und committen Sie ihn nicht.

Was ist die Basis-URL und der erste Aufruf?

Basis https://api.app.firstsales.io, Bearer-Authentifizierung. Erster Aufruf GET /api/v1/whoami, um Organisation und Workspace-Kontext vor jeder Schreiboperation zu bestätigen.

Wie verhindere ich doppelte Schreibvorgänge bei Wiederholungen?

Senden Sie bei Erstellungsanfragen einen Idempotency-Key-Header. Eine Wiederholung mit demselben Schlüssel liefert das ursprüngliche Ergebnis zurück, statt einen zweiten Datensatz zu erzeugen.

Was darf Codex niemals tun?

Niemals app-interne Routen, Provider-Callbacks, Tracking-Pixel, Unsubscribe-Handler oder interne Cron-Endpunkte aufrufen und niemals die App-Oberfläche scrapen. Bleiben Sie auf den öffentlichen /api/v1-Endpunkten; bei unsupported_operation stoppen und melden.

Bereit, das in die Praxis umzusetzen?

Starten Sie Ihre FirstSales-Testphase und richten Sie in wenigen Minuten ein aufgewärmtes, authentifiziertes Postfach ein.

Für 1 $ starten

Alle Tutorials