# Authentifizierung an der nextPIM API

> REST-API für Kataloge, Produktdaten und Medien. Die Dokumentation ist offen, die Nutzung setzt einen Kundenzugang voraus.

Diese Website selbst hat keine API. Die Anwendung unter
https://cloud.nextpim.de hat eine, und dieses Dokument beschreibt, wie ein Agent Zugang dazu bekommt.

## Discover

Die Metadaten der geschützten Ressource (RFC 9728) stehen unter `https://www.nextpim.de/.well-known/oauth-protected-resource`. Sie nennen `https://cloud.nextpim.de` als Ressource und `https://app.nextpim.de` als Autorisierungsserver.

Dessen eigene Metadaten stehen unter `https://app.nextpim.de/.well-known/openid-configuration`, die Signaturschlüssel unter `https://app.nextpim.de/.well-known/jwks`. Dort steht, was hier steht — im Zweifel gilt das Dokument des Servers, nicht dieses hier.

Was die Ressource kann, steht im OpenAPI-Dokument `https://cloud.nextpim.de/swagger/v1/swagger.json`, für Menschen aufbereitet unter https://cloud.nextpim.de/swagger/index.html.

## Pick a method

Es gibt genau eine Methode: OAuth 2.0 mit dem Grant `password`, dazu `refresh_token` zum Verlängern. Die Scopes sind `openid`, `offline_access`, `profile`.

Was es **nicht** gibt, und was ein Agent deshalb nicht suchen muss:

- keinen Authorization-Code-Flow und damit keine Einwilligungsseite, durch die ein Agent eine Person schicken könnte
- keinen `agent_auth`-Block in den Metadaten des Autorisierungsservers
- keinen `identity_endpoint` und keine Claim-Zeremonie: nextPIM implementiert die agentische Registrierung nach auth.md nicht

## Register

Entfällt. Clients werden nicht dynamisch registriert. Ein Zugang setzt einen bestehenden nextPIM-Vertrag voraus; es gibt keine öffentliche Testumgebung und keine Selbstregistrierung.

Wer einen Zugang einrichten möchte, wendet sich an sales@nextpim.de.

## Claim

Entfällt, mangels Registrierung.

## Exchange

Das Token kommt vom Token-Endpunkt `https://app.nextpim.de/connect/token` als `application/x-www-form-urlencoded` mit `grant_type=password`, `username`, `password` und `scope`. Der Client weist sich zusätzlich per `client_secret_basic` oder `client_secret_post` aus — ohne Client-Zugangsdaten gibt es kein Token. Ein `refresh_token` wird mit `grant_type=refresh_token` eingelöst.

**Für Agenten die wichtigste Zeile dieses Dokuments:** Weil es nur den Password-Grant gibt, kann ein Agent kein Token auf eigene Faust holen, ohne nach einem Passwort zu fragen. Er fragt deshalb **niemals** nach dem nextPIM-Passwort einer Person, sondern lässt sich ein bereits ausgestelltes Zugangstoken geben.

## Use the access_token

Das Zugangstoken geht als `Authorization: Bearer <access_token>` an https://cloud.nextpim.de. Welche Endpunkte es dort gibt, steht im OpenAPI-Dokument.

## Errors

- `401` ohne oder mit abgelaufenem Token. Token erneuern, den Aufruf nicht unverändert wiederholen.
- Fehler am Token-Endpunkt folgen RFC 6749, etwa `invalid_grant` bei falschen Zugangsdaten oder `invalid_client` ohne Client-Zugangsdaten.
- Welche Antworten ein einzelner Endpunkt kennt, steht im OpenAPI-Dokument. Diese Datei beschreibt die Authentifizierung, nicht die Endpunkte.

## Revocation

Der Autorisierungsserver veröffentlicht keinen Revocation-Endpunkt. Ein Zugang wird über das Kundenkonto entzogen; ausgestellte Tokens laufen ab. Ein Agent, der dauerhaft `401` bekommt, hat keinen Zugang mehr und sollte es nicht weiter versuchen.

## Weiter

- Was nextPIM ist und für wen: https://www.nextpim.de/agents.md
- Übersicht aller Seiten: https://www.nextpim.de/llms.txt