Workspace-Admin-API

Die Workspace-Admin-API ermöglicht Server-zu-Server-Integrationen zur Verwaltung eines EVCharge-Workspaces. Diese Dokumentation richtet sich an Workspace-Administratoren und externe Integratoren. Sie verwendet widerrufbare workspacegebundene Tokens und feingranulare Scopes; Kunden-Anmeldetokens und Browsersitzungen werden nicht akzeptiert.

Dieses Verzeichnis ist die maßgebliche Entwicklerreferenz für die von app-api implementierte /v2/admin-API. Es dokumentiert weder Kunden-/Mobilrouten noch die eigenen HTTP-Routen des Admin-Portals.

• Endpunktanfragen und -antworten führt alle 87 registrierten Endpunkte, Scopes, Parameter, Anfrage-Bodys und Erfolgs-Bodys auf.
• Schemas und Beispiele definiert wiederverwendbare Anfrage-/Antworttypen und repräsentative JSON-Bodys.
• Antwort- und Fehlervertrag definiert jeden gemeinsamen und endpunktspezifischen Fehler-Body.

Basis-URL und Ressourcengrenze

Alle Routen sind relativ zum bereitgestellten Origin app-api:

https://api.evcharge.mobi/v2/admin/...

Workspace-IDs werden weder in URL, Query noch Body akzeptiert. Jedes Token gehört genau einem Workspace; die API leitet cpoId aus dem authentifizierten Token-Prinzipal ab. Gehört ein verschachtelter Standort, Ladegerät, Benutzer, Tarif, Profil, Zuweisung oder Transaktion nicht dazu, liefert sie dieselbe nicht auskunftgebende 404 RESOURCE_NOT_FOUND-Antwort.

Zugriffstoken erhalten

Ein menschlicher Workspace-Administrator erstellt Tokens in den Workspace-Einstellungen unter API-Zugriff. Die Tokenverwaltung steht Workspace-Tokens bewusst nicht zur Verfügung.

• API-Zugriff ist in jedem Paket enthalten, auch in Free. Der Administrator benötigt Bearbeitungsrechte für den Workspace.
• Der Workspace-Host muss die Admin-API über adminApiEnabled aktivieren; andernfalls erhält ein gültiges Token ein nicht auskunftgebendes 404 von app-api.
• Der Administrator darf nur Scopes vergeben, die seine aktuellen Rechte und die Workspace-Funktionsberechtigungen erlauben.
• Neue Tokens können unbefristet sein (Standard in den Workspace-Einstellungen) oder eine vom Administrator gewählte Lebensdauer von 1–365 ganzen Tagen haben; der Server berechnet das absolute Ablaufdatum. Unbefristete Tokens bleiben bis zum Widerruf gültig.
• Ein Workspace kann höchstens 50 aktive Tokens haben.
• Die Zugangsinformation wird einmal im Klartext angezeigt. Speichern Sie sie sofort in einem Secret-Manager.
• Name, Scopes und Ablaufzeit sind unveränderlich. Zur Rotation erstellen, verteilen und prüfen Sie einen Ersatz und widerrufen das alte Token.
• Ein Widerruf wirkt sofort. Widerrufene Zeilen bleiben als unveränderlicher, geschwärzter Workspace-Verlauf sichtbar. Es gibt weder Bearer-Token-Introspektion noch einen Endpunkt zum endgültigen Löschen.

app-api bietet keinen Endpunkt zum Ausstellen, Aktualisieren, Auflisten oder Widerrufen dieser Zugangsdaten. Der Tokenbezug erfolgt daher vorab über das menschlich bediente Admin-Portal, nicht über einen weiteren hier beschriebenen Endpunkt.

Speichern Sie das Token niemals in der Versionsverwaltung, in URLs, Abfrageparametern, Cookies, Logs, Analysedaten oder Fehlerberichten.

Authentifizierung

Senden Sie bei jeder Anfrage genau einen Header gemäß RFC 6750:

Authorization: Bearer evc_ws_<selector>.<secret>

Die exakte opake Zugangsinformation besteht aus evc_ws_, einem 16-stelligen kanonischen Base64url-Selektor, . und einem 43-stelligen kanonischen Base64url-Geheimnis. Senden Sie sie vollständig und unverändert; kodieren Sie sie nicht erneut als Base64.

Die API weist doppelte Autorisierungsheader, kommaverknüpfte Werte, andere Schemata, leere Bearer-Werte, Kunden-JWTs und außerhalb dieses Headers übergebene Zugangsdaten zurück.

Fehlerhafte, unbekannte, abgelaufene, widerrufene oder anderweitig ungültige Tokens erhalten dieselbe Antwort:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Cache-Control: no-store
Content-Type: application/json

{
  "error": "Unauthorized",
  "code": "INVALID_WORKSPACE_TOKEN"
}

Der Dienst prüft bei jeder Anfrage Tokenstatus und aktuelle Workspace-Berechtigungen. Das Entfernen einer Berechtigung kann betroffene Scopes daher vor Tokenablauf deaktivieren.

Workspace-Tokens sind opake Zugangsdaten, keine JWTs. Sie haben kein Refresh-Token und keinen Refresh-Endpunkt. Befristete Tokens verlieren bei ihrem absoluten expiresAt die Gültigkeit; unbefristete gelten bis zum Widerruf. Rotation bedeutet, im Portal Ersatzdaten zu erstellen, im Client einzusetzen und die alten zu widerrufen.

Anfragekonventionen

• Verwenden Sie Content-Type: application/json für Anfragen mit JSON-Body.
• Optionale Anfragewerte X-Request-Id werden getrimmt und nur mit 1–128 Zeichen aus A-Z, a-z, 0-9, ., _, : oder - akzeptiert; sonst erzeugt der Server eine UUID. Jede Antwort gibt den gewählten Wert als X-Request-Id zurück.
• Optionales X-Error-Format: envelope wandelt jede JSON-Fehlerantwort in den unter Antwort- und Fehlervertrag dokumentierten strukturierten Umschlag um. Jeder andere Wert behält den Standard-Kompatibilitäts-Body bei.
• IDs in Pfadparametern sind positive Ganzzahlen. Vom Portal gelieferte Zugriffstoken-IDs sind Dezimalzeichenfolgen, da sie vorzeichenlose 64-Bit-Datenbankwerte darstellen.
• Datums- und Zeitwerte sind RFC-3339-Zeichenfolgen mit ausdrücklichem Offset, zum Beispiel 2026-08-13T12:30:00Z.
• Erfolgreiche Löschvorgänge liefern normalerweise 204 No Content.
• Erstellungsvorgänge liefern normalerweise 201 Created.
• OCPP-Arbeit, die lediglich eingereiht wurde, kann 202 Accepted liefern. Dies ist keine Bestätigung des Geräts, sofern die Antwort das nicht ausdrücklich sagt.
• Authentifizierte Antworten verwenden Cache-Control: no-store. QR- und Berichtsexport-Endpunkte liefern Binärdaten mit ausdrücklichen Inhaltsheadern.
• Zugelassene Browser-Origins können X-Request-Id, Idempotency-Replayed, Retry-After und Content-Disposition über CORS lesen. So können Browserclients Anfragen zuordnen, idempotente Wiederholungen erkennen, Wartezeiten einhalten und serverseitig gewählte Downloadnamen übernehmen.

Idempotenz

Alle Admin-Anfragen mit POST, PUT, PATCH und DELETE müssen einen Idempotency-Key-Header enthalten. Schlüssel bestehen aus 1–255 sichtbaren Zeichen und gelten für Token, Methode und Pfad.

Idempotency-Key: provisioning-2026-08-13-site-42

Ein abgeschlossener Schlüssel mit identischer URL und identischem Body spielt die gespeicherte Antwort erneut ab und ergänzt:

Idempotency-Replayed: true

Derselbe Schlüssel mit anderer Anfrage liefert 409 IDEMPOTENCY_CONFLICT. Eine noch verarbeitete Anfrage liefert 409 IDEMPOTENT_REQUEST_PROCESSING mit Retry-After: 5.

Abgeschlossene Antworten und endgültige Ergebnisse werden ab ihrer letzten Aktualisierung sieben Tage für Wiederholung oder Abgleich aufbewahrt. Danach kann derselbe Schlüssel als neuer Befehl gelten. Clients müssen daher global eindeutige Schlüssel verwenden und dürfen sie nicht absichtlich wiederverwenden.

Läuft eine Verarbeitungssperre ab, endet die Verbindung nach Ausführungsbeginn oder liefert der Vorgang einen Serverfehler, kann die API eine externe Wirkung nicht sicher feststellen. Während der siebentägigen Aufbewahrung bleibt der Schlüssel endgültig unbestimmt und liefert 409 IDEMPOTENCY_OUTCOME_UNKNOWN; er wird weder erneut übernommen noch automatisch ausgeführt. Prüfen Sie vor manueller Wiederherstellung die Wirkungen und senden Sie denselben Vorgang bis zum abgeschlossenen Abgleich nicht mit einem neuen Schlüssel.

Alle schreibenden Admin-Endpunkte, einschließlich POST /reports/send, benötigen Idempotency-Key.

Anfragelimits

Grenzen gelten sowohl für das einzelne Token als auch für dessen Workspace. Die im Repository festgelegten Standardwerte sind:

Eine gedrosselte Anfrage liefert 429 Too Many Requests und einen Retry-After-Header. Bereitstellungen können diese Werte überschreiben.

Fehler

JSON-Fehler verwenden ein stabiles code, wenn der Aufrufer danach verzweigen muss:

{
  "error": "Insufficient workspace-token scope",
  "code": "INSUFFICIENT_SCOPE"
}

Validierungsfehler verwenden Feld-Arrays:

{
  "validationErrors": {
    "name": ["String must contain at least 1 character(s)"]
  }
}

Häufige Statuswerte sind:

Scope-Katalog

Der folgende Scope-Katalog wird bei der Token-Erstellung verwendet. Schreibende oder besonders wirksame Scopes können den entsprechenden Lese-Scope einschließen, Lese-Scopes gewähren jedoch niemals Schreibrechte. Verfügbare Scopes hängen von Administratorrechten und aktivierten Workspace-Funktionen ab.

Der API-Zugriff selbst ist in jedem Paket enthalten und wird über die Host-Einstellung adminApiEnabled gesteuert. Die oben genannten zusätzlichen Funktionsberechtigungen gelten weiterhin; API-Zugriff gewährt keine Funktionen außerhalb des Workspace-Pakets.

Endpunktreferenz

Die folgenden Tabellen enthalten alle 87 Workspace-Admin-Routen. Mehrere Scopes in einer Zelle sind sämtlich erforderlich.

Workspace

Workspace-Patch-Felder: name, email, website, addressLine1, addressLine2, postalCode, city, state und countryId. Mindestens ein Feld ist erforderlich. Leere nullfähige Zeichenfolgen werden zu null normalisiert.

Standorte und Leistungsmanagement

Bodys zum Erstellen und Ändern eines Standorts verwenden:

{
  "name": "Main depot",
  "description": null,
  "addressLine1": "1 Example Street",
  "addressLine2": null,
  "postalCode": "LV-1001",
  "city": "Riga",
  "state": null,
  "countryId": 1,
  "timezoneId": 1,
  "latitude": 56.9496,
  "longitude": 24.1052
}

Standort-Geocoding akzeptiert optionale Query-Felder street, city, state, country und zweistelliges countryCode sowie Anfrageheader Accept-Language. Straße/Ort/Region müssen zusammen mindestens zwei Zeichen umfassen. Antworten enthalten nur placeId, displayName, latitude und longitude; Anbieterzugangsdaten und spezifische Metadaten werden nicht ausgegeben. Der Server nutzt die gemeinsame Warteschlange mit einer Anfrage pro Sekunde, acht Sekunden Timeout, begrenzten 24-Stunden-Cache und globale Workspace-Token-Limits.

Leistungsmanagement akzeptiert { "pools": [...] }. Ein Pool hat id, name, limit, optional meterSources und rekursives children. Ein untergeordnetes Ladegerät hat chargepointId und priority. Die API begrenzt Baum- und Zähleranzahl und führt beim Ersetzen installierten Zustands zweiphasiges OCPP-Löschen mit erneuter Prüfung durch. Abgelehnte, abgelaufene oder konkurrierende Änderungen liefern 409 POWER_MANAGEMENT_CONFLICT und erhalten die vorige Konfiguration.

Ladegeräte

Abfrageparameter für Ladegerätelogs sind cursor, limit (Standard 50, höchstens 200), from, to, action, direction und levelId. Für Ladevorgänge gelten page, limit (Standard 25, höchstens 100), from, to und customerId (positive ID oder unknown). Der Verlauf kombinierter Zeitpläne nutzt cursor, limit (Standard 20, höchstens 50) und optional connectorId.

Berichte

Berichts- und Exportfilter sind from, to, siteId, chargerId, userId, anonymous und active. from/to verwenden standardmäßig die letzten 90 Tage und dürfen höchstens 90 Tage umfassen. userId lässt sich nicht mit anonymous=true kombinieren.

• Datenpaginierung: opakes cursor, Standard limit=50, höchstens 100.
• Messungen: erforderliches transactionLogId, opakes cursor, Standard limit=500, höchstens 1.000.
• Export: format=csv|pdf, Standard csv, feste Obergrenze 2.000 Zeilen.
• Exportantworten verwenden Content-Disposition: attachment, Cache-Control: private, no-store und X-Content-Type-Options: nosniff.

Zeitplan-Body:

{
  "enabled": true,
  "recipientEmail": "reports@example.com",
  "format": "csv",
  "sendDay": 5,
  "sendTime": "08:30"
}

sendDay liegt zwischen 1 und 28, sendTime wird in UTC interpretiert. Der Scheduler holt eine verpasste Minute im aktuellen Zustellmonat nach. Fehlgeschlagene Erstellung vor Übergabe wird nach 5 und 10 Minuten wiederholt; eine unterbrochene building-Reservierung ist nach 30 Minuten übernehmbar. Nach drei Versuchen endet die Automatik. Unmittelbar vor SMTP-Übergabe speichert er indeterminate; indeterminate und der alte Status sending sind endgültig, da erneuter Versand doppelte Anhänge erzeugen könnte. Betreiber müssen diese Ergebnisse vor Änderung des Zeitplanstatus manuell abgleichen. Jeder Takt wählt höchstens zehn Zeitpläne, startet nach 45 Sekunden keine weitere Arbeit und verwendet begrenzte SMTP-Timeouts. Der Job ist standardmäßig deaktiviert und muss nach SMTP- und Kapazitätsprüfung ausdrücklich aktiviert werden. Der API-Zeitplan gehört dem Workspace, nicht der Identität des Token-Erstellers.

Tarife

Ein Tarif-Body enthält name, genau eines von currencyId, currencyCode oder currency, optional biddingZoneId und tax. Ein Zuweisungs-Body lautet:

{ "tariffId": 17, "connectorId": 0 }

Beim Anlegen einer Zuweisung gilt der Tarif für alle physischen Anschlüsse, wenn connectorId weggelassen oder ausdrücklich auf 0 gesetzt wird. Aktualisierungen betreffen eine gespeicherte Zuweisung und erfordern daher eine ausdrücklich positive physische connectorId; 0 wird abgelehnt.

Eine Komponente enthält typeId, seasonId, price, optional priority sowie optionale Gültigkeitsgrenzen für Monat, Wochentag und Stunde.

Ladeprofile

Profilmetadaten sind label, locationId, stackLevel, purposeId, kindId, optional recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId und optional minChargingRate. Ein Zeitplanabschnitt enthält startPeriod, limit und optional numberOfPhases. Ein Zuweisungs-Body enthält profileId und connectorId (Standard 0).

Profillöschungen und das Ersetzen des Leistungsmanagements können auf Gerätebestätigung warten. Ablehnung, Zeitüberschreitung oder konkurrierende Änderung erzeugen einen Konflikt und erhalten die Datenbankkonfiguration, statt eine erfolgreiche Gerätelöschung vorzutäuschen.

Benutzer, Einladungen, RFID, Zugriff und Grenzen

Fahrzeugpaginierung und status=members-Benutzerpaginierung verwenden positives numerisches cursor. Einladungen nutzen opaken Cursor i2.*, während status=all nach der ersten Seite einen opaken zusammengesetzten a2.*-Cursor verwendet; numerische Cursor bleiben nur für alte Mitgliederfortsetzungen gültig. Benutzersuche erfolgt im Anfrageheader X-Admin-User-Search, damit E-Mails nicht in URLs oder Zugriffslogs erscheinen. limit ist standardmäßig 50, höchstens 100; die Benutzerliste unterstützt status=all|members|invitations. Behandeln Sie alle zurückgegebenen Cursor als opak und senden Sie sie unverändert zurück.

Die direkte Benutzererstellung erzeugt kein Passwort, keine Anmeldeidentität und keine Sitzung. Sie ordnet nur einen bereits registrierten Kunden zu. Für unbekannte E-Mail-Adressen verwenden Sie den Einladungsendpunkt. Der geschützte Tagless-Systembenutzer kann über diese Routen nicht geändert werden.

Beispiele

Setzen Sie Werte in Ihrer Shell, ohne das Token auszugeben:

export ADMIN_API_BASE_URL="https://api.example.com"
export WORKSPACE_TOKEN="<read from secret manager>"

Standorte auflisten:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Standort sicher erstellen:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-main-depot-v1" \
  --data '{
    "name":"Main depot",
    "description":null,
    "addressLine1":"1 Example Street",
    "addressLine2":null,
    "postalCode":"LV-1001",
    "city":"Riga",
    "state":null,
    "countryId":1,
    "timezoneId":1,
    "latitude":56.9496,
    "longitude":24.1052
  }' \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Laden Sie einen CSV-Bericht für einen ausdrücklich angegebenen UTC-Zeitraum herunter:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -o report.csv \
  "${ADMIN_API_BASE_URL}/v2/admin/reports/export?format=csv&from=2026-07-01T00%3A00%3A00Z&to=2026-08-01T00%3A00%3A00Z"

Bewusste Ausschlüsse

Die Workspace-Token-API bietet keine Vorgänge, die einen menschlichen Prinzipal oder weitergehende Befugnisse erfordern. Dazu gehören:

• Tokens mit einem anderen Token erstellen, offenlegen, rotieren oder widerrufen;
• Anmeldung, Passwortzurücksetzung, Sitzungen, menschliche Rollen-/Rechtedelegation und Workspace-Besitzänderungen;
• Workspace-Erstellung/-löschung und Mitgliedschaft im Abrechnungskonto;
• Zahlungseinstellungen, Stripe-Onboarding, Pakete, Rechnungen und Host-Abrechnung;
• hostweite Supportvorgänge und Anbieter-Webhooks;
• menschliche Benachrichtigungen, Navigationsumleitungen, Markenmaterial sowie Entwicklungs-/Testrouten.