REST-API & Tokens

Die Weboberfläche hat keine versteckte Seite: Alles, was sie tut, läuft über die REST-API unter /api/v1/. Du kannst also alles davon auch aus einem Skript heraus erledigen. Skripte, CI-Jobs, die Kommandozeile und MCP nutzen sie mit API-Tokens.

Einen Token anlegen

Geh auf Einstellungen → API-Tokens & MCP, gib unter Neuer Token einen Namen ein, wähl den Scope, beschränke ihn bei Bedarf auf Projekte und klick auf Token erstellen. Den Wert (er beginnt mit stq_) siehst du genau einmal - kopier ihn also gleich, denn Envoryx speichert nur einen Hash und kann ihn nicht noch einmal zeigen. Ist ein Token in falsche Hände geraten, widerrufst du ihn; das gilt sofort.

Du schickst ihn als Bearer-Token mit. Solche Anfragen brauchen weder ein Sitzungs-Cookie noch die CSRF-Header, die ein Browser mitsendet:

curl -H "Authorization: Bearer stq_…" https://envoryx.test/api/v1/projects
curl -H "Authorization: Bearer stq_…" -X POST https://envoryx.test/api/v1/projects/<id>/restart

Token-Scopes

Ein Token muss nicht alles können, und meistens sollte er das auch nicht. Es gibt drei Stufen, und jede schließt die darunter ein:

Scope	Erlaubt
read	Ansehen: Projektliste und Details, Status, Logs, Statistiken, Backup-Liste, Runtimes. Keine Geheimnisse (auch nicht die Werte geheimer Variablen), keine Änderungen.
operate	Mit bestehenden Projekten arbeiten: starten/stoppen/neu starten, Image-Rollback, Aktionen, Backups und Datenbanken anlegen, Git, Domains, Addons, SSH/SFTP, Terminal, Datenbank-Browser. Standard für neue Tokens.
admin	Alles, was ein Admin darf: Projekte anlegen und löschen, Einstellungen, TLS, Benachrichtigungen, Instanz-Backups, Wiederherstellungen, Datenbanken verwerfen.

Zusätzlich kannst du einen Token auf bestimmte Projekte beschränken. Er sieht dann nur diese, jedes andere Projekt antwortet mit 403, instanzweite Endpunkte sind zu, und Projekte anlegen kann er nicht - egal welcher Scope. Menschen bekommen dieselben Stufen als Rollen. Genau das Richtige für einen CI-Job, der ein Projekt ausrollen soll und sonst nichts.

Darf ein Token etwas nicht, steht der Grund in der Antwort (this token has read scope, the operation needs operate). GET /api/v1/auth/me zeigt Name, Scope und Projekte des Tokens, mit dem du gerade anfragst. Ein paar Dinge kann kein Token: das Passwort ändern, Tokens anlegen oder widerrufen, Benutzer verwalten und den Secret Key anzeigen oder ersetzen. Dafür brauchst du eine Browser-Sitzung, für die letzten beiden die eines Admins.

Einige Endpunkte

Nicht die vollständige Liste, aber die, zu denen du zuerst greifst:

Endpunkt	Zweck
GET /api/v1/projects	alle Projekte
POST /api/v1/projects	ein Projekt anlegen
PATCH /api/v1/projects/{id}	Runtimes und Dienste ändern, z. B. {"ruby": {"enabled": true, "version": "3.4", "server": true}}
POST /api/v1/projects/{id}/start · /stop · /restart	Lebenszyklus
GET /api/v1/runtimes	Versionen, Templates und Presets, die Envoryx anbietet
GET /api/v1/projects/{id}/tests	Test-Suites und letzte Läufe
GET/POST/DELETE /api/v1/projects/{id}/share	eine öffentliche Freigabe
PUT /api/v1/projects/{id}/proxy-rules	die Proxy-Regeln des Projekts
GET /api/v1/audit · /audit/export	das Audit-Log
GET /api/v1/system/diagnostics	die Einrichtungsprüfung (admin)
GET /api/v1/health	Health, ohne Anmeldung

Ein paar Dinge bei PATCH auf Dienste ersparen dir Überraschungen. Was du weglässt, bleibt, wie es ist: {"memcached": {"exposePort": false}} nimmt nur den Port vom Host und lässt den Dienst stehen. {"redis": {"enabled": false}} entfernt Redis, behält aber seine Daten; mit "removeData": true werden sie gelöscht. Genauso bei RabbitMQ, Meilisearch, Typesense und OpenSearch. GET /api/v1/projects/{id}/extras listet behaltene Daten unter keptData, und DELETE /api/v1/projects/{id}/extras/{kind}/data löscht sie. Mailpit und Meilisearch veröffentlichen ihren Port immer, "exposePort": false beantworten sie deshalb mit 422. Ein neuer Bucket ist privat, außer du schickst bei storage ein "publicRead": true mit.

Bei Runtimes ist es genauso. {"go": {"enabled": true, "version": "1.27"}} ändert die Version und behält den Server, seinen Modus, sein Paket und seinen Port; lässt du version weg, bleibt auch die Version. Das gilt für jede Runtime, Nodes devServer eingeschlossen. Nur ein neues Preset ist die Ausnahme: Es verwirft den gespeicherten Port (und bei Python die Anwendung), wenn du sie nicht mitschickst. Du kannst ein Runtime-Objekt auch genau so zurückschicken, wie GET es geliefert hat: Die schreibgeschützten Felder hostPort und debugHostPort darin nimmt Envoryx an und ignoriert sie. Als Datenbanktyp bedeuten postgres und postgresql beide PostgreSQL, wie in envoryx.yml.

Projekte tragen in der API ihre vollständige url, samt Port des Proxys. Die Zugangsdaten der Dienste (Schlüssel des Objektspeichers, das RabbitMQ-Passwort, die Keys von Meilisearch und Typesense, das Passwort eines externen Redis) stehen nicht in den Projekt-Antworten, genau wie Datenbank-Passwörter. Die erzeugten kommen aus den Credentials-Endpunkten wie GET /api/v1/projects/{id}/storage/credentials, und die brauchen operate.

Aktionen, Terminals und Testläufe streamen ihre Ausgabe über WebSockets (…/tests/{suite}/ws und ähnliche). Aus einem Shell-Skript heraus ist das etwas fummelig - deshalb verpackt die CLI das für dich.

Jede Änderung über die API landet als benutzer (token: name) im Audit-Log. So siehst du auch später noch, welches Skript was gemacht hat.