Den Kunden wählen, bei jedem Aufruf.

Im Agenturmodus können Monitore und andere Ressourcen zu einem Kunden gehören. Die API kennt keinen „aktuellen Kunden“: Jede Anfrage sagt, welche Kunden sie meint, und der Schlüssel entscheidet, welche er sehen darf.

Der Agenturmodus muss an sein

Kunden stehen zur Verfügung, wenn der Agenturmodus für das Unternehmen eingeschaltet ist. Solange er aus ist:

• Jeder Kunden-Endpunkt, etwa GET /clients, antwortet mit 404 Not found.
• Listen-Endpunkte ignorieren client_id und all_clients und liefern nur Ressourcen auf Unternehmensebene.

Beim Lesen Kunden wählen

Ressourcen, die zu einem Kunden gehören können, tragen ein optionales client_id: Monitore, Geplante Aufgaben, Statusseiten, Vorfälle, Alarmpläne, Bereitschaftspläne und Anleitungen. Eine Ressource ohne dieses Feld liegt auf Unternehmensebene. Listen-Endpunkte nehmen zwei Query-Parameter:

export CLIENT_ID="…"   # aus GET /clients

curl -s -G https://app.upfour.io/v1/monitors \
  -H "Authorization: Bearer $UP4_API_KEY" \
  --data-urlencode "client_id=$CLIENT_ID"

curl -s -G https://app.upfour.io/v1/monitors \
  -H "Authorization: Bearer $UP4_API_KEY" \
  --data-urlencode "all_clients=true"

• all_clients zählt nur, wenn der Wert genau true ist.
• Ein client_id, das keine UUID ist, führt nicht zu einem Fehler. Der Aufruf fällt auf Ressourcen der Unternehmensebene zurück.
• Einen Header dafür gibt es nicht. Die Wahl gehört zu jeder einzelnen Anfrage, nicht zum Schlüssel.

Beim Schreiben einen Kunden wählen

Aufrufe zum Anlegen und Ändern nehmen client_id im JSON-Body entgegen. Lässt du es weg, liegt die Ressource auf Unternehmensebene.

curl -s -X POST https://app.upfour.io/v1/monitors \
  -H "Authorization: Bearer $UP4_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Lakeside Bakery site",
    "url": "https://example.com",
    "monitor_type": "http",
    "client_id": "'"$CLIENT_ID"'"
  }'

• Einen Monitor mit einem client_id anzulegen, der kein Kunde deines Unternehmens ist oder zu einem archivierten Kunden gehört, ergibt 400 bad_request.
• Ein Schlüssel, der bei diesem Kunden nicht schreiben darf, bekommt 403 mit der Meldung „You do not have write access to this client“.

Auf Kunden beschränkte Schlüssel

Ein Schlüssel lässt sich beim Anlegen in der App auf ausgewählte Kunden beschränken. Was ein Schlüssel sehen darf, ist sein Kundenset: bei einem persönlichen Schlüssel das, was sein Besitzer sehen darf, eingeengt auf die gewählten Kunden; bei einem Team-Schlüssel die Kunden seines Teams plus Ressourcen der Unternehmensebene. GET /me zeigt es:

"client_set": { "All": false, "CompanyLevel": true, "IDs": ["…", "…"] }

• Listen enthalten nie Kunden außerhalb des Sets, egal was du in client_id übergibst.
• Eine einzelne Ressource außerhalb des Sets, etwa ein Monitor, antwortet mit 404 und nicht mit 403, damit sich IDs anderer Kunden nicht abtasten lassen.
• Routen der Unternehmensebene wie /organization antworten Team-Schlüsseln und Schlüsseln, die Ressourcen der Unternehmensebene nicht lesen dürfen, mit 404.

Typische Fehler

• Einen Monitor ohne client_id anlegen und dann mit client_id auflisten. Der Monitor liegt auf Unternehmensebene und taucht nicht auf.
• all_clients=True oder all_clients=1 übergeben. Nur true wirkt; alles andere heißt Unternehmensebene.
• Einen Fehler erwarten, wenn der Agenturmodus aus ist. Die Parameter werden ohne Meldung ignoriert.
• client_id als Header senden. Einen Header dafür gibt es nicht.
• Zwischen den Seiten den Kunden wechseln. Die Cursor-Prüfung erfasst ihn nicht; lass ihn bei jeder Seite gleich.