REST-API einrichten

Jedes NimbusNexus-Produkt ist eine REST-API: JSON über HTTPS, mit Ihrem API-Key im Header Authorization. Diese Seite führt Sie vom fehlenden Key bis zum ersten erfolgreichen Aufruf. Wählen Sie oben auf der Seite eine Sprache, und die Beispiele folgen ihr. REST bedeutet curl; TypeScript, Python und Go verwenden den üblichen HTTP-Client der jeweiligen Sprache, ohne dass ein SDK nötig ist.

1 · API-Key erstellen

Apps: Webhooks, Inboxes, QR-Codes und Request Bins. Öffnen Sie API keys in Ihrer Kontokonsole und erstellen Sie einen Key für das Produkt, das Sie aufrufen wollen. Jeder Key gehört zu genau einem Produkt. Wählen Sie dort seinen Scope: admin, read oder bei Webhooks auch publish. Kopieren Sie den Key, sobald er erscheint, denn er wird nur einmal angezeigt. Ein App-Key ist ein JWT und beginnt daher mit eyJ.

Infrastruktur: VMs, Speicher, Datenbanken und Netzwerk. Erstellen Sie den Key im Dashboard unter Settings → API keys. Er gilt für genau ein Projekt. Authentifizierung behandelt Scopes und Rotation.

Halten Sie den Key aus Ihrem Quellcode heraus. Exportieren Sie ihn in Ihrer Shell oder bewahren Sie ihn in Ihrem Secret-Store auf:

Shell

export WEBHOOKS_API_KEY="<your-api-key>"

2 · Key bei jedem Request senden

Senden Sie den Key als Bearer-Token. Die APIs der Apps akzeptieren ihn auch als X-API-Key: <key>.

HTTP

Authorization: Bearer <your-api-key>

Jedes Produkt hat eine eigene Basis-URL:

Produkt	Basis-URL
Webhooks	`https://webhooks.nimbusnexus.net/v1`
Inboxes	`https://inboxes.nimbusnexus.net/v1`
QR-Codes	`https://qr.nimbusnexus.net/v1`
Request Bins	`https://bins.nimbusnexus.net/v1`
Infrastruktur	`https://api.nimbusnexus.net`

3 · Ersten Aufruf senden

GET /v1/auth/me bei Webhooks gibt den Key zurück, den Sie gesendet haben: seinen Scope und den Workspace, zu dem er gehört. Der Aufruf liest nichts anderes, daher kann ihn jeder gültige Key aufrufen.

curl https://webhooks.nimbusnexus.net/v1/auth/me \
  -H "Authorization: Bearer $WEBHOOKS_API_KEY"

Die Antwort nennt Ihren Workspace:

JSON

{
  "scope": "admin",
  "workspace_id": "<workspace-id>"
}

Die übrigen Felder geben an, um welche Art von Credential es sich handelt. Bei einem API-Key haben email und created_at den Wert null.

4 · Fehler lesen

Ein fehlgeschlagener Request antwortet mit einem Status 4xx oder 5xx und mit einem einheitlichen Fehlerformat für alle Produkte:

JSON

{
  "error": {
    "code": "unauthorized",
    "message": "…",
    "details": { "reason": "missing" },
    "request_id": "…"
  }
}

Verzweigen Sie anhand von code, nicht anhand des Status oder der Nachricht. unauthorized bedeutet, dass kein Key ankam oder der Key widerrufen wurde. invalid_credential bedeutet, dass der Key ungültig ist: Erstellen Sie einen neuen, denn eine Wiederholung hilft nicht. forbidden bedeutet, dass der Key gültig ist, dies aber nicht darf: Ihm fehlt der Scope oder die Rolle, oder das Produkt ist für Ihren Workspace nicht aktiviert. Authentifizierung und Fehler listen alle Codes auf. Geben Sie die request_id an, wenn Sie den Support kontaktieren.

Nächste Schritte

API-Referenz: jede Operation jedes Produkts, mit dem Aufruf in Ihrer Sprache.
SDKs und die CLI: dieselben Aufrufe, wobei Retries, Signaturprüfung und Paginierung für Sie übernommen werden.
Schnellstarts der Produkte: Webhooks, Inboxes, Request Bins, Ihre erste VM.