# Kunden-Scope

> Wie ein API-Aufruf im Agenturmodus einen Kunden wählt: die Query-Parameter client_id und all_clients, client_id in Request-Bodys, auf Kunden beschränkte Schlüssel und was bei ausgeschaltetem Agenturmodus passiert.

Source: https://upfour.io/de/docs/api/client-scope

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:

| Du sendest | Du bekommst |
| --- | --- |
| nichts | Nur Ressourcen auf Unternehmensebene. |
| `client_id=<uuid>` | Die Ressourcen genau dieses Kunden. |
| `all_clients=true` | Alles, was der Schlüssel sehen darf: alle Kunden und Ressourcen auf Unternehmensebene. Der Parameter geht vor `client_id`. |

```bash
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.

```bash
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": ["…", "…"] }
```

| Feld | Bedeutung |
| --- | --- |
| `All` | Der Schlüssel darf jeden Kunden sehen. |
| `CompanyLevel` | Der Schlüssel darf Ressourcen der Unternehmensebene sehen. |
| `IDs` | Die Kunden, die der Schlüssel sehen darf, wenn er beschränkt ist, sonst `null`. |

- 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](https://upfour.io/de/docs/api/pagination.md) erfasst ihn nicht; lass ihn bei jeder Seite gleich.