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.
Die Liste der Applikationen
Abschnitt betitelt „Die Liste der Applikationen“
- Mit Applikation erstellen legen Sie einen neuen Zugang an.
- Neben dem Namen steht Aktiv oder Deaktiviert, bei unbegrenzter Gültigkeit zusätzlich Unbegrenzt.
- Client-ID: Mit dem Symbol daneben (Client-ID kopieren) kopieren Sie sie.
- Gültigkeitsdauer der Tokens und die Anzahl Umleitungs-URLs (Keine, wenn es keine gibt).
- Über ⋮ erreichen Sie alle Aktionen für die Applikation, siehe unten.
Eine Applikation erstellen
Abschnitt betitelt „Eine Applikation erstellen“
- Klicken Sie auf Applikation erstellen und geben Sie einen Name ein, zum Beispiel «HR-System».
- Beschreibung: optional, welches System diesen Zugang nutzt.
- 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.
- 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. - Anwendungsbereiche (Scope): welche Angaben die Applikation über
angemeldete Personen erhält.
openid,profile,emailundmobilesind eingeschaltet; ein Klick schaltet einen Bereich aus oder ein. Unter weiterer … tragen Sie einen eigenen Bereich ein. - 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.
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.
Client-ID und Geheimnis sichern
Abschnitt betitelt „Client-ID und Geheimnis sichern“Direkt nach dem Erstellen zeigt actaSIGN die Client-ID und das Geheimnis (Client Secret). Beide erzeugt actaSIGN selbst.
- Kopieren Sie die Client-ID mit Kopieren.
- Kopieren Sie das Geheimnis (Client Secret) mit Kopieren und bewahren Sie es sicher auf. Es wird nur dieses eine Mal angezeigt.
- Setzen Sie das Häkchen Ich habe das Geheimnis sicher gespeichert.
- 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.
Einen unbegrenzten Bearer-Token erzeugen
Abschnitt betitelt „Einen unbegrenzten Bearer-Token erzeugen“Kann das andere System keinen Token selbst abholen, erzeugen Sie einen Bearer-Token und geben ihn Ihrem Integrator.
- Öffnen Sie ⋮ → Bearbeiten, wählen Sie bei Gültigkeitsdauer der Tokens die Einheit Unbegrenzt und klicken Sie auf Speichern.
- Ö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.
- 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.
- 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.
Eine Applikation ändern, sperren oder löschen
Abschnitt betitelt „Eine Applikation ändern, sperren oder 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. |
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.»
Tokens ungültig machen
Abschnitt betitelt „Tokens ungültig machen“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.
Auch in actaPASS
Abschnitt betitelt „Auch in actaPASS“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.
Gut zu wissen
Abschnitt betitelt „Gut zu wissen“- 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.