API-Zugang einrichten: Token erstellen und verwalten

Über die Prepaid-Hoster API (v2) steuerst du deine Dienste programmatisch. Die API ist REST-basiert, verwendet JSON und wird über einen persönlichen API-Token authentifiziert.

Hinweis: Die API befindet sich aktuell noch in der Entwicklung. API-Keys stehen noch nicht generell zur Verfügung und Routen können sich noch ändern. Wir rollen das Feature nach und nach an Interessenten und anschließend alle Kunden aus.

Auf einen Blick

  • Basis-URL: https://api.pph.systems/api
  • Format: REST, JSON
  • Authentifizierung: Authorization: Bearer <API-TOKEN>
  • Die aktuell aktive API-Version wird dir direkt im API-Bereich angezeigt.

Token anlegen

  1. Melde dich in deinem Kundenbereich (Vionity) an.
  2. Öffne den Bereich API v2.
  3. Trage rechts unter Neuen Token erstellen eine Beschreibung ein, damit du den Token später wiedererkennst (zum Beispiel „Uptime Monitor“ oder „Backup-Skript“).
  4. Optional: Setze den Haken bei Mit Schreibrechten erstellen, wenn der Token nicht nur lesen, sondern auch Daten verändern soll.
  5. Klick auf Erstellen. Der Token wird dir im Format sk_live_... angezeigt.

Kopiere den Token direkt nach der Erstellung und bewahre ihn sicher auf. Über Settings kannst du ihn später jederzeit anpassen oder widerrufen.

Lese- oder Schreibrechte

Jeder Token hat eine von zwei Berechtigungsstufen, die du unter Schreibrechte einstellst:

  • Nur Lesezugriff: Der Token darf Daten ausschließlich abfragen. Ideal für Monitoring, Reporting oder Dashboards.
  • Mit Schreibrechten: Der Token darf zusätzlich Daten anlegen, ändern und löschen. Nutze diese Stufe nur, wenn dein Anwendungsfall das wirklich braucht.

Faustregel: Vergib so wenig Rechte wie möglich. Ein Monitoring-Token braucht keinen Schreibzugriff.

Authentifizierung

Sende den Token bei jeder Anfrage im Authorization-Header mit:

curl -H "Authorization: Bearer sk_live_..." \
     https://api.pph.systems/api/vps

Gated Routes: Zugriff gezielt einschränken

Standardmäßig kann ein Token alle Routen ansprechen, die seine Berechtigungsstufe erlaubt. Mit Gated Routes schränkst du das weiter ein. Ist die Funktion aktiv, darf der Token nur noch auf die Routen zugreifen, die du explizit freigibst. Jeder andere Aufruf wird mit einem HTTP 403 abgewiesen.

Eine Route gibst du unter Neue Route freigeben frei. Dabei stehen dir zwei Mechanismen zur Verfügung.

Wildcards

Statt jede Route einzeln zu pflegen, gibst du mit * ganze Gruppen frei:

  • vps.status.index gibt genau eine Route frei.
  • vps.* gibt alle VPS-Routen frei.
  • domains.records.* gibt alle DNS-Record-Routen frei.

Route-Param Binding

Über die Felder Hosting IDs und Domain IDs bindest du eine Route an konkrete Ressourcen. Der Token kann die Route dann nur für genau diese IDs nutzen.

Beispiel: Gibst du vps.* zusammen mit einer bestimmten Hosting-ID frei, darf der Token alle VPS-Aktionen ausführen, aber ausschließlich auf diesem einen Server. Lässt du die Felder leer, gilt die Route ohne Einschränkung auf einzelne Ressourcen.

So baust du dir zum Beispiel einen Token, der nur den Status eines einzelnen VPS abfragen darf und sonst nichts.

MCP-Fähigkeit

Tokens lassen sich optional für die Nutzung mit MCP-Servern (Model Context Protocol) freischalten, etwa um die API direkt an einen KI-Assistenten anzubinden. Diese Fähigkeit ist standardmäßig nicht verfügbar und wird pro Account manuell freigeschaltet. Wenn du sie nutzen möchtest, melde dich bei unserem Support.

Human in the loop (Coming soon)

Für Tokens mit Schreibrechten kannst du Human in the loop aktivieren. Bestimmte Aktionen, die der Token auslöst, müssen dann zusätzlich von einem Menschen bestätigt werden, bevor sie ausgeführt werden. Das ist sinnvoll, wenn ein Token automatisiert läuft, kritische Aktionen aber nicht ohne manuelle Freigabe durchgehen sollen.

Token widerrufen

Einen Token deaktivierst du sofort, indem du in den API-Token Details den Haken bei Token widerrufen setzt und speicherst. Ein widerrufener Token wird ab der nächsten Anfrage abgewiesen.

Noch Fragen?

Technische Fragen zur API beantworten dir unsere Entwickler direkt in unserem Discord. Stell deine Frage im Entwickler-Channel und pinge das Dev-Team an.