Basis · jeder Tarif
Enclessa bietet eine HTTP-API, beschrieben durch ein OpenAPI-3.1-Dokument, das aus dem Server generiert wird, statt neben ihm geschrieben zu werden — mit einem CI-Job, der den Build scheitern lässt, sobald beide voneinander abweichen. Der Zugriff erfolgt per Token: ein persönliches Zugriffstoken, das als Sie handelt, oder ein Bot-Token, das als der Bot selbst handelt. Jedes Token trägt Scopes aus einem geschlossenen Vokabular, muss binnen eines Jahres ablaufen und wird nur als Hash seiner selbst gespeichert.
Aktualisiert
- Beschreibung
- OpenAPI 3.1, aus dem Server generiert
- Abweichung
- Ein CI-Job lässt den Build scheitern, wenn Dokument und Code voneinander abweichen
- Scopes
- Ein geschlossenes Vokabular; ein unbekannter Scope wird abgelehnt, nicht ignoriert
- Ablauf
- Verpflichtend, 1 bis 365 Tage, standardmäßig 90
- Speicherung
- Ein Hash des Tokens, nie das Token
- Reichweite
- Nur Operationen, die ausdrücklich für Token geöffnet sind
Was erlaubt mir ein Token?
Genau das, was seine Scopes sagen, auf der Teilmenge der Operationen, die ausdrücklich für die Token-Authentifizierung geöffnet wurden. Alles andere antwortet einem Token mit 401, wie hochrangig sein Inhaber auch sein mag. Das Scope-Vokabular ist geschlossen: Kanäle lesen, Nachrichten lesen und schreiben, Reaktionen hinzufügen, Benutzer lesen sowie Aufgaben lesen und schreiben. Wer einen Scope anfordert, der nicht in der Liste steht, wird abgewiesen, statt dass der Scope stillschweigend fallen gelassen wird.
- channels:read, messages:read, messages:write, reactions:write, users:read, tasks:read, tasks:write
- Ein unbekannter Scope ist ein Fehler, kein ignoriertes Feld
- Ein Token erreicht einen bewusst schmalen Ausschnitt der Schnittstelle; der Rest antwortet mit 401
- Scopes begrenzen, was ein Konto tun kann — sie erweitern es nie
Wie laufen Token ab, und wie werden sie widerrufen?
Jedes Token hat ein Ablaufdatum, weil eine Richtlinie mit der Option „nie“ keine Richtlinie ist. Sie wählen zwischen einem und 365 Tagen, Standard sind 90. Ablauf, Widerruf und der Status des Inhabers werden gemeinsam in einer einzigen Abfrage aufgelöst, also gibt es keine Lücke zwischen dem Deaktivieren eines Kontos und dem Ungültigwerden seiner Zugangsdaten.
- Jedes Mitglied kann seine eigenen persönlichen Zugriffstoken in den Kontoeinstellungen ausstellen und widerrufen
- Eine Administratorin stellt Bot-Token in der Konsole aus und widerruft sie dort
- Der Wert wird einmal angezeigt; gespeichert wird nur sein Hash
- Wird der Inhaber deaktiviert, ist das Token beim nächsten Aufruf ungültig, ohne eigenen Widerrufsschritt
Woher weiß ich, dass die Dokumentation zur Software passt?
Weil sie keine Dokumentation im üblichen Sinn ist. Das OpenAPI-Dokument wird aus den Routendefinitionen des Servers generiert und ins Repository eingecheckt, und ein CI-Job generiert es bei jeder Änderung neu und lässt den Build bei jeder Abweichung scheitern. Eine Beschreibung, die nicht abweichen kann, ist mehr wert als eine, die bloß gründlich ist.
- Aus dem Code generiert, nicht daneben gepflegt
- Eine Abweichungsprüfung in der CI, damit beide nicht still auseinanderlaufen
- Aus demselben Dokument wird ein TypeScript-Client generiert
- Dasselbe Dokument treibt eine generierte organisationsübergreifende Prüfsuite, die den Build scheitern lässt, wenn die Trennung nachlässt
Was es nicht leistet
Hier gesagt, statt erst nach der Anmeldung entdeckt.
- Es gibt noch keine gehostete API-Referenz und keine veröffentlichte Client-Bibliothek. Der generierte TypeScript-Client liegt im Repository, nicht in einer Paket-Registry.
- Ein Token erreicht nur die Operationen, die ausdrücklich dafür geöffnet wurden, und das ist ein kleiner Teil der gesamten Schnittstelle. Das wird bewusst Schritt für Schritt wachsen, nicht auf einmal.
- Es gibt keinen OAuth2-Autorisierungsablauf, also kann ein Drittanbieter eine Nutzerin nicht um Zugriff auf ihr Enclessa-Konto bitten. Token werden von ihrem Inhaber ausgestellt und in Ihre eigene Software eingefügt.
- Es gibt keine Webhooks aus der Plattform heraus und keinen Ereignisstrom für Integratoren. Um zu erfahren, dass etwas passiert ist, fragen Sie ab.
- Nichts in der API kann einen Ende-zu-Ende-verschlüsselten Raum lesen. Der Server hält Chiffretext, und kein Scope ändert das.
- Ratengrenzen gelten pro Organisation nach Anfrageklasse, nicht pro Token. Eine viel beschäftigte Integration teilt sich ein Budget mit den Menschen, die das Produkt nutzen.
Verwandte Seiten
Fragen
- Ja. Enclessa bietet eine HTTP-API, beschrieben durch ein OpenAPI-3.1-Dokument, das aus dem Server selbst generiert wird, mit einem CI-Job, der den Build scheitern lässt, wenn Dokument und Code jemals voneinander abweichen.
- Mit einem Zugriffstoken. Jedes Mitglied kann in den Kontoeinstellungen ein persönliches Zugriffstoken ausstellen, und eine Administratorin kann ein Token für ein Bot-Konto ausstellen. Jedes Token trägt Scopes aus einem geschlossenen Vokabular und muss binnen eines Jahres ablaufen.
- Immer. Der Ablauf ist verpflichtend, zwischen einem und 365 Tagen, standardmäßig 90. Ein Token ohne Ablauf gibt es nicht, weil eine Richtlinie mit der Option „nie“ keine ist.
- Aus dem OpenAPI-Dokument wird ein TypeScript-Client generiert, aber er ist noch nicht in einer Paket-Registry veröffentlicht, und es gibt keine gehostete API-Referenz. Heute generieren Sie einen Client aus dem Dokument oder rufen die Endpunkte direkt auf.
- Sie können Software bauen, die die API mit einem Token nutzt, das Ihnen gegeben wurde. Es gibt aber keinen OAuth2-Ablauf, also kann Ihre Software die Nutzer einer anderen Organisation nicht um Zugriff bitten. Und es gibt keinen App-Marktplatz, in dem Sie sie listen könnten.
Legen Sie in ein paar Minuten einen Workspace an. Er gehört Ihnen, erreichbar unter your-team.enclessa.app, betrieben in der Europäischen Union, mit Ende-zu-Ende-verschlüsselten Direktnachrichten ab der ersten.