Zum Inhalt springen

Applikationen für die API verwalten

Soll ein anderes System (zum Beispiel Ihr HR-System oder ERP) Anfragen über die Programmierschnittstelle (API) senden, braucht es einen Zugang: eine Applikation mit Client-ID und Geheimnis. Diese legen Sie hier an und geben sie Ihrem Integrator.

Bereich Applikationen mit einer Applikation: Name, Aktiv, Unbegrenzt, Client-ID mit Kopier-Symbol, Gültigkeitsdauer der Tokens und Umleitungs-URLs
  1. Mit Applikation erstellen legen Sie einen neuen Zugang an.
  2. Neben dem Namen steht Aktiv oder Deaktiviert, bei unbegrenzter Gültigkeit zusätzlich Unbegrenzt.
  3. Client-ID: Mit dem Symbol daneben (Client-ID kopieren) kopieren Sie sie.
  4. Gültigkeitsdauer der Tokens und die Anzahl Umleitungs-URLs (Keine, wenn es keine gibt).
  5. Über ⋮ erreichen Sie alle Aktionen für die Applikation, siehe unten.
Dialog Neue Applikation mit Name, Beschreibung, Gültigkeitsdauer der Tokens, erlaubten Umleitungs-URLs und Anwendungsbereichen
  1. Klicken Sie auf Applikation erstellen und geben Sie einen Name ein, zum Beispiel «HR-System».
  2. Beschreibung: optional, welches System diesen Zugang nutzt.
  3. Gültigkeitsdauer der Tokens: wie lange ein Token gilt, den das andere System abholt. Geben Sie eine Zahl ein und wählen Sie Stunde(n), Tag(e), Woche(n), Monat(e) oder Jahr(e), oder Unbegrenzt. Neue Applikationen beginnen mit 30 Tagen.
  4. Erlaubte Umleitungs-URLs: nur nötig, wenn sich Personen über diese Applikation anmelden. Geben Sie eine vollständige Adresse mit https:// ein und klicken Sie auf Hinzufügen. Für einen reinen API-Zugang lassen Sie das leer.
  5. Anwendungsbereiche (Scope): welche Angaben die Applikation über angemeldete Personen erhält. openid, profile, email und mobile sind eingeschaltet; ein Klick schaltet einen Bereich aus oder ein. Unter weiterer … tragen Sie einen eigenen Bereich ein.
  6. Klicken Sie auf Applikation erstellen.

Was die einzelnen Einheiten bedeuten und wie gross die Zahl höchstens sein darf, steht bei der actaPASS-Anwendung; das Feld folgt in beiden Apps denselben Regeln.

Gültigkeitsdauer der Tokens mit der Auswahl Unbegrenzt und dem gelben Warnhinweis

Wählen Sie Unbegrenzt, warnt actaSIGN: Ein unbegrenzter Token läuft nie ab. Wer ihn besitzt, kann damit im Namen dieser Applikation arbeiten. Wählen Sie wenn möglich eine begrenzte Dauer.

Direkt nach dem Erstellen zeigt actaSIGN die Client-ID und das Geheimnis (Client Secret). Beide erzeugt actaSIGN selbst.

Dialog mit Client-ID und unkenntlich gemachtem Geheimnis, Warnhinweis, Häkchen Ich habe das Geheimnis sicher gespeichert und Schaltfläche Fertig
  1. Kopieren Sie die Client-ID mit Kopieren.
  2. Kopieren Sie das Geheimnis (Client Secret) mit Kopieren und bewahren Sie es sicher auf. Es wird nur dieses eine Mal angezeigt.
  3. Setzen Sie das Häkchen Ich habe das Geheimnis sicher gespeichert.
  4. Klicken Sie auf Fertig. Vorher lässt sich der Dialog nicht schliessen.

Geht das Geheimnis verloren, erzeugen Sie ein neues (⋮ → Neues Geheimnis erzeugen). Das bisherige gilt danach nicht mehr.

Kann das andere System keinen Token selbst abholen, erzeugen Sie einen Bearer-Token und geben ihn Ihrem Integrator.

  1. Öffnen Sie ⋮ → Bearbeiten, wählen Sie bei Gültigkeitsdauer der Tokens die Einheit Unbegrenzt und klicken Sie auf Speichern.
  2. Öffnen Sie ⋮ bei der Applikation und wählen Sie Bearer-Token erzeugen. Den Eintrag gibt es nur bei einer aktiven Applikation, deren gespeicherte Gültigkeitsdauer Unbegrenzt ist.
  3. actaSIGN holt den Token bei actaPASS ab und zeigt ihn einmal an, mit dem Datum, bis wann er gültig ist. Kopieren Sie ihn mit Kopieren.
  4. Setzen Sie das Häkchen Ich habe den Token sicher gespeichert und klicken Sie auf Fertig.

Das andere System sendet den Token bei jeder API-Anfrage im Header Authorization: Bearer … mit. Jeder Klick auf Bearer-Token erzeugen erzeugt einen neuen Token; frühere bleiben gültig, bis Sie sie wie unten beschrieben ungültig machen.

Geöffnetes Menü einer Applikation mit Bearbeiten, Bearer-Token erzeugen, Neues Geheimnis erzeugen, Deaktivieren und Löschen
Eintrag im Menü ⋮ Was passiert
Bearbeiten Name, Beschreibung, Gültigkeitsdauer, Umleitungs-URLs und Anwendungsbereiche ändern. Eine neue Gültigkeitsdauer gilt für Tokens, die ab jetzt ausgegeben werden.
Bearer-Token erzeugen Siehe oben.
Neues Geheimnis erzeugen Nach einer Rückfrage ein neues Geheimnis, einmal angezeigt wie beim Erstellen. Das bisherige funktioniert nicht mehr, und alle Tokens der Applikation werden sofort ungültig.
Deaktivieren Nach einer Rückfrage erhält die Applikation keine Tokens mehr, und alle bestehenden Tokens werden sofort ungültig.
Aktivieren Steht bei einer deaktivierten Applikation. Sie kann wieder Tokens abholen; die beim Deaktivieren ungültig gemachten Tokens bleiben ungültig.
Löschen Nach einer Rückfrage (Endgültig löschen) wird die Applikation gelöscht, und alle ihre Tokens werden sofort ungültig. Das lässt sich nicht rückgängig machen.
Rückfrage Applikation deaktivieren mit dem Hinweis, dass alle bestehenden Tokens sofort ungültig werden

Nach dem Deaktivieren, Löschen oder einem neuen Geheimnis meldet actaSIGN, wie viele Tokens ungültig gemacht wurden, zum Beispiel «2 Token(s) wurden ungültig gemacht.»

Um einen Token sofort zu sperren, etwa weil er in falsche Hände geraten ist, wählen Sie in actaSIGN bei der Applikation ⋮ → Neues Geheimnis erzeugen, Deaktivieren oder Löschen. Alle noch gültigen Tokens der Applikation werden dann sofort ungültig, in actaSIGN und in actaPASS, auch die Tokens aus Bearer-Token erzeugen. Das andere System braucht danach ein neues Geheimnis bzw. einen neuen Token.

Wollen Sie nur die Tokens sperren und das Geheimnis behalten (zum Beispiel weil ein Bearer-Token weitergegeben wurde, das Geheimnis aber sicher ist), wählen Sie ⋮ → Deaktivieren und danach ⋮ → Aktivieren. Das andere System holt sich danach mit seinem Geheimnis neue Tokens; einen neuen Bearer-Token erzeugen Sie wie oben beschrieben.

Dieselben Applikationen sehen und ändern Sie auch in actaPASS unter API-Zugang für andere Systeme einrichten (dort «Anwendungen»). Eine Änderung an einem Ort gilt sofort auch am anderen.

  • In actaSIGN (empfohlen): nur hier machen Neues Geheimnis erzeugen, Deaktivieren und Löschen die bestehenden Tokens sofort ungültig.
  • In actaPASS: wenn Sie ein Firmenkonto mit mehreren Mandanten betreuen. Sperren Sie Tokens trotzdem in actaSIGN. actaPASS kennt kein Deaktivieren; eine deaktivierte Applikation aktivieren Sie in actaSIGN wieder.
  • Ungültig werden die Tokens, die die Applikation selbst abgeholt hat oder die mit Bearer-Token erzeugen entstanden sind. Personen, die sich über die Applikation im Browser angemeldet haben, bleiben angemeldet.
  • Eine deaktivierte Applikation steht gestrichelt und grau in der Liste. Für sie können Sie keinen Bearer-Token erzeugen.
  • Geheimnis und Token erscheinen nie im Audit-Log. Dort steht nur, wer eine Applikation erstellt, geändert, deaktiviert, gelöscht oder einen Token erzeugt hat, und wie viele Tokens dabei ungültig wurden.
  • Meldet actaSIGN «actaPASS hat keinen Token ausgegeben», versuchen Sie es später erneut. Bleibt der Fehler, wenden Sie sich an den Support.