Developer API

Im Tab “Developers” stellen Sie API-Schlüssel für den programmatischen Zugriff auf Entergram aus. Verfügbar im Pro-Tarif (und bei Pro-Workspace-Sitzen). Nur Owner und Admins.

Einen Schlüssel erstellen

1. “API-Schlüssel erstellen”
2. Benennen Sie ihn (etwas, das Sie später in einer Widerrufsliste wiedererkennen)
3. Wählen Sie Scopes — feingranulare Berechtigungen wie z. B.:
   • workspace.read
   • members.read
   • accounts.read
   • contacts.read
   • chats.read / chats.write
   • custom_fields.read / custom_fields.write
4. Standard-TTL beträgt 90 Tage; Sie können eine kürzere Dauer wählen
5. Optional: auf eine Liste von IP-CIDR-Bereichen einschränken
6. Klicken Sie auf “Erstellen” — der vollständige Schlüssel wird einmal angezeigt. Kopieren Sie ihn sofort; Entergram zeigt ihn nie wieder an.

Unter der Haube

• Schlüssel werden als Einweg-Hashes gespeichert — der rohe Schlüssel liegt nie auf der Festplatte
• Jede Anfrage protokolliert Präfix, IP und User-Agent zur Auditierung
• Widerruf erfolgt sofort
• Abgelaufene Schlüssel geben automatisch 403 zurück
• Jeder API-Aufruf ist workspace-bezogen — ein Schlüssel kann nur auf dem Workspace operieren, der ihn ausgestellt hat

Schlüssel verwalten

Im Tab “Developers”:

• Sehen Sie zu jedem Schlüssel Präfix, Erstellungsdatum, Scopes, TTL und Informationen zur letzten Nutzung
• Präfix kopieren (nicht das Geheimnis)
• Einen Schlüssel widerrufen oder rotieren
• Rotieren = einen neuen Schlüssel mit denselben Scopes erstellen, dann den alten widerrufen, sobald Ihre Integration umgestellt ist

Beispiel: einen geleakten Schlüssel rotieren

1. Sie merken, dass ein Entwickler einen Schlüssel in einen öffentlichen Issue Tracker eingefügt hat
2. Tab “Developers” → Schlüssel finden → Widerrufen (sofort wirksam)
3. Erstellen Sie einen neuen Schlüssel mit denselben Scopes und derselben IP-Allowlist
4. Stellen Sie den neuen Schlüssel in Ihrer Integration bereit
5. Prüfen Sie die Info zur letzten Nutzung des alten Schlüssels, um zu bestätigen, dass kein Traffic mehr fließt

Beispiel: einen Schlüssel für einen CI-Job ausstellen

1. Tab “Developers” → API-Schlüssel erstellen
2. Benennen Sie ihn ci-deploy-bot
3. Scopes: nur workspace.read und chats.read (geringste Rechte)
4. TTL: 30 Tage
5. IP-Allowlist: die Egress-IPs des CI-Anbieters
6. Schlüssel kopieren und als Secret in CI hinterlegen
7. Vor Ablauf der TTL rotieren

Make.com-Integration

Pro-Tarife enthalten eine Make.com-Integration, sodass Sie Entergram in Low-Code-Automatisierungen einbinden können, ohne selbst API-Code zu schreiben. Verfügbar im Workspace-Integrationsbereich.

API-Antworten

Häufige HTTP-Fehler, die Ihnen begegnen:

• 401 — der Schlüssel ist abgelaufen, widerrufen oder falsch für den Workspace
• 403 — dem Schlüssel fehlt der benötigte Scope, oder die Anfrage stammt von einer IP außerhalb der Allowlist
• 429 — Sie haben ein Rate-Limit erreicht; warten Sie ab und versuchen Sie es erneut