---
icon: rocket
title: Erste Schritte
description: Erstellen Sie eine Fuxam-API-v4-Integration, bauen Sie Basic Auth auf, rufen Sie GET /users auf, lesen Sie das Response-Envelope und paginieren Sie Ihre erste Liste.
---

Dieser Leitfaden führt Sie von null zu einer funktionierenden authentifizierten Anfrage an die Fuxam API v4. Am Ende haben Sie eine Integration erstellt, einen `Authorization`-Header gebaut, `GET /users` aufgerufen, das Envelope `{ data, meta }` interpretiert und mit einem Cursor eine zweite Seite abgerufen.

**Base URL:** `https://fuxam.app/api/v4`

## Warum das wichtig ist

Ein erster erfolgreicher Aufruf beweist drei Dinge zugleich: Ihre Zugangsdaten funktionieren, Ihr Netzwerkpfad zu `fuxam.app` ist offen, und Ihr Client parst die gemeinsame Antwortform korrekt. Diese Grundlagen früh richtig zu setzen, verhindert stundenlanges Debuggen, wenn Sie später Writes, Retries und mehrseitige Sync-Jobs hinzufügen.

## Bevor Sie beginnen

Sie benötigen:

- Zugriff auf die Organisationseinstellungen Ihrer Institution in Fuxam Web, um eine API-Integration zu erstellen.
- Ein Terminal mit `curl` (oder einem beliebigen HTTP-Client, der Basic Auth senden kann).
- Einen sicheren Ort zur Speicherung des `clientSecret` — behandeln Sie ihn wie ein Passwort.

Weiterführende Lektüre: [Authentifizierung](/docs/de/api/authentication) zur Sicherheit von Zugangsdaten, [Übersicht](/docs/de/api/overview) für die vollständige Konventionsübersicht und [Nutzerverwaltung](/docs/de/fuxam-web/base/user-management) dazu, wie Nutzer in der Produkt-UI erscheinen.

```mermaid
flowchart LR
  Create[Integration erstellen] --> Auth[Basic Auth aufbauen]
  Auth --> Call[GET users]
  Call --> Read[data und meta lesen]
  Read --> Page[Mit Cursor paginieren]
```

## So erstellen Sie eine Integration

1. Öffnen Sie in Fuxam Web **Organisation → API-Integrationen**.

2. Erstellen Sie eine neue Integration und notieren Sie `clientId` und `clientSecret`, sobald sie angezeigt werden. Speichern Sie das Secret sofort — Sie brauchen es für jede Anfrage.

3. Bestätigen Sie, dass die Integration für Ihre Institution aktiv ist, bevor Sie Aufrufe machen. Zugangsdaten sind institutionsbezogen; sie sehen nur die Daten dieser Institution.

:::warning[Client Secret schützen]
Jeder mit `clientId` und `clientSecret` kann die API als Ihre Integration aufrufen. v4 Basic Auth ist Alles-oder-nichts — es gibt keine Berechtigungs-Scopes. Siehe [Authentifizierung](/docs/de/api/authentication).
:::

## So bauen Sie den Authorization-Header

HTTP Basic Auth kodiert `clientId:clientSecret` als Base64 und sendet es im `Authorization`-Header:

```http
Authorization: Basic <base64(clientId:clientSecret)>
```

Erzeugen Sie den Wert in Ihrer Shell (Platzhalter ersetzen):

```bash
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH=$(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n')
echo "Authorization: Basic $AUTH"
```

:::tip
Lassen Sie Ihre HTTP-Bibliothek Basic Auth aus Benutzername/Passwort setzen, statt Base64 selbst zu bauen, sobald Sie über `curl` hinausgehen. Bibliotheken handhaben Padding und Zeichenkodierung konsistent.
:::

## So machen Sie Ihre erste Anfrage

Listen Sie Nutzer mit `GET /users`. Das ist ein sicherer Nur-Lese-Aufruf und ein guter Smoke-Test.

```bash
curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=25"
```

Äquivalentes Raw-HTTP:

```http
GET /api/v4/users?limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

Eine erfolgreiche Antwort sieht so aus:

```json
{
  "data": [
    { "id": "usr_123", "email": "user@example.com" },
    { "id": "usr_456", "email": "another@example.com" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "limit": 25
  },
  "meta": {
    "requestId": "req_1700000000000_abc123",
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v4"
  }
}
```

### Das Envelope lesen

| Feld | Rolle |
|---|---|
| `data` | Die Ressource oder Liste von Ressourcen. Bei Listen ist das immer ein Array. |
| `pagination` | Bei Listenantworten vorhanden: `next_cursor`, `has_more`, `limit`. |
| `meta.requestId` | Diese Antwort bei der Fehleranalyse mit Server-Logs korrelieren. |
| `meta.timestamp` | Serverzeit der Antwort. |
| `meta.version` | Auf dieser API immer `"v4"`. |

Bewahren Sie `meta.requestId` auf, wenn Sie ein Support-Ticket öffnen — so finden Sie die Anfrage am schnellsten.

## So paginieren Sie

Wenn `pagination.has_more` `true` ist, fordern Sie die nächste Seite mit dem undurchsichtigen `next_cursor`-Wert an:

```bash
curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=25&cursor=${NEXT_CURSOR}"
```

```http
GET /api/v4/users?limit=25&cursor=eyJpZCI6MTIzfQ== HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

Stoppen Sie, wenn `has_more` `false` ist. Erfinden oder bearbeiten Sie Cursor nicht — sie sind HMAC-signiert und an Ihre Institution und Integration gebunden. Ein ungültiger Cursor liefert `400` mit dem Code `invalid_cursor`.

Vollständige Details (einschließlich einer kompletten Schleife über alle Seiten) finden Sie unter [Paginierung und Filterung](/docs/de/api/pagination-and-filtering).

## Checkliste nach dem ersten Aufruf

| Prüfung | Erwartung |
|---|---|
| HTTP-Status | `200` |
| Body-Form | `data`-Array plus `meta` (und meist `pagination`) |
| `meta.version` | `"v4"` |
| Auth-Fehler | `401` bei falschen Zugangsdaten — Secret neu erzeugen oder erneut kopieren |
| Leeres `data` | Gültig, wenn Ihre Institution noch keine passenden Nutzer hat |

## Best Practices für erste Integrationen

- Beginnen Sie mit **Listen-Reads** (`GET /users`, `GET /courses`), bevor Sie erstellen oder aktualisieren.
- Loggen Sie `meta.requestId` bei jeder Antwort in Ihrem Integrationsclient.
- Nutzen Sie während der Entwicklung ein moderates `limit` (zum Beispiel `25`); erhöhen Sie erst bei Syncs im großen Maßstab Richtung `100`.
- Speichern Sie Zugangsdaten in einem Secrets-Manager, nicht in der Quellkontrolle. Siehe [Authentifizierung](/docs/de/api/authentication).
- Wenn Sie schreiben möchten, folgen Sie [Fehler und Idempotenz](/docs/de/api/errors-and-idempotency) und den Mustern in [Rezepte](/docs/de/api/recipes).

## Häufige Fallstricke

| Symptom | Wahrscheinliche Ursache | Was tun |
|---|---|---|
| `401` Unauthorized | Falsches `clientId`/`clientSecret` oder kaputtes Base64 | Zugangsdaten erneut kopieren; `-u` mit `curl` statt Handkodierung nutzen |
| Leeres `data`-Array | Keine passenden Ressourcen oder unerwartete Filter | Bestätigen Sie, dass Nutzer in der [Nutzerverwaltung](/docs/de/fuxam-web/base/user-management) existieren |
| `400` `invalid_cursor` | Cursor über Integrationen hinweg wiederverwendet oder bearbeitet | Neue Liste von der ersten Seite starten |
| Client parst nur `data` | `pagination` / `meta` ignoriert | Modellieren Sie das volle Envelope in Ihren Typen |

## FAQ

**Welchen Endpunkt sollte ich zuerst aufrufen?**

`GET /users` ist ein zuverlässiger Smoke-Test: er ist nur lesend und liefert das Standard-Listen-Envelope. Öffnen Sie die Referenz [Nutzer](/docs/de/api/users/users/list-users) für die vollständigen Operationsdetails.

**Brauche ich eine andere Base URL für Staging?**

Dieses Handbuch dokumentiert die Produktions-Base-URL `https://fuxam.app/api/v4`. Verwenden Sie Host und Pfad, die Ihrer Institution für jede Nicht-Produktionsumgebung mitgeteilt wurden.

**Kann ich eine Integration auf Nur-Lesen beschränken?**

v4 Basic Auth ist für die Integration Alles-oder-nichts — API-Key-Berechtigungs-Scopes sind nicht implementiert. Steuern Sie den Zugriff darüber, wer Integrationen erstellen darf und was Ihr Client-Code aufrufen darf.

## Verwandte Seiten

**[Authentifizierung](/docs/de/api/authentication)**

Zugangsdaten, Rotation und Sicherheitspraxis.

**[Paginierung und Filterung](/docs/de/api/pagination-and-filtering)**

Cursor, Felder und Filter im Detail.

**[API-Übersicht](/docs/de/api/overview)**

Konventionen und Index zum Durchsuchen nach Ressource.

**[Nutzer-Referenz](/docs/de/api/users/users/list-users)**

Generierte Endpunktreferenz für Nutzer.
