Einen API-Schlüssel erstellen

Mit API-Schlüsseln kann ein anderes System AssinaJá steuern – Ihr ERP, das Dokumente erstellt, oder ein KI-Assistent, der über die MCP-Schnittstelle arbeitet. Erstellen Sie einen pro externem System oder KI-Assistenten, mit Berechtigungen, die auf das beschränkt sind, was diese Integration braucht.

Einstellungen → Entwickler hat die Registerkarten Allgemein, API-Schlüssel, Webhooks, Integrationen und Speicher – die letzten beiden nur für Inhaber und Administrator. Allgemein öffnet sich zuerst, mit den Adressen der Öffentliche API und des MCP-Server sowie dem Link API-Dokumentation öffnen.

Die Schlüssel finden Sie unter API-Schlüssel, und verwalten darf sie nur der Inhaber der Organisation. Bei jeder anderen Rolle öffnet sich die Registerkarte, zeigt die Schlüssel aber nicht an.

Ein Schlüssel pro Integration

Erstellen Sie für jedes externe System, das die öffentliche API nutzt (Header X-Api-Key), einen eigenen Schlüssel. Jeder Schlüssel kann einzeln gesperrt oder gelöscht werden, ohne die übrigen Integrationen zu beeinträchtigen.

Das ist der Grund für die Regel: Ein gemeinsam genutzter Schlüssel lässt sich nicht widerrufen, ohne alles lahmzulegen, was ihn verwendet. Ein Schlüssel pro System erlaubt es, eine Integration abzuschalten und die anderen weiterlaufen zu lassen.

Einen Schlüssel erstellen

Wählen Sie Neuer API-Schlüssel.

1. Name – benennen Sie ihn nach dem System, das ihn verwenden wird, zum Beispiel ERP DATEV. Wenn Sie möchten, fügen Sie eine Beschreibung hinzu.
2. Gültig bis – „Der Schlüssel ist bis einschließlich dieses Datums gültig (er authentifiziert ab Ende dieses Tages nicht mehr).“
3. Berechtigungen – markieren Sie nur, was diese Integration braucht. Mindestens eine ist Pflicht: „Wählen Sie mindestens eine Berechtigung – der Schlüssel kann nur das tun, was markiert ist.“
4. Schlüssel erstellen.

Der Schlüssel wird nur ein einziges Mal angezeigt

Kopieren und speichern Sie diesen Schlüssel jetzt: Er wird nur dieses eine Mal angezeigt und nirgends gespeichert. Falls Sie ihn verlieren, verwenden Sie „Schlüssel rotieren“, um einen neuen mit denselben Berechtigungen zu erzeugen.

Später lässt er sich nicht wiederherstellen. Neben Kopieren gibt es Als Umgebungsvariable kopieren, das ASSINAJA_API_KEY= gefolgt vom Schlüssel kopiert, bereit zum Einfügen in eine Konfigurationsdatei. Der Dialog schließt sich erst, wenn Sie Ich habe den Schlüssel sicher gespeichert angekreuzt haben.

Berechtigungen

Berechtigung	Was sie erlaubt
Vorlagen – lesen	Vorlagen auflisten und abrufen, einschließlich Unterzeichnern und Ausfüllfeldern.
Dokumente – lesen	Dokumente auflisten, den Fortschritt der Signaturen verfolgen sowie Dateien und Berichte herunterladen.
Dokumente – Signaturlinks	Die Signaturlinks der ausstehenden Unterzeichner abrufen. Wer den Link hat, unterschreibt im Namen des Unterzeichners – das ist ein Zugangsnachweis, keine Abfrage.
Dokumente – erstellen	Dokumente aus Vorlagen, aus DOCX (MailMerge) oder aus einem eigenen PDF erstellen.
Dokumente – versenden	Entwürfe versenden – sendet E-Mails an die Unterzeichner und kann nicht rückgängig gemacht werden.
Dokumente – archivieren/löschen	Dokumente archivieren und löschen.
Organisation – lesen	Die Daten der Organisation, den aktiven Tarif und die verfügbaren Funktionen anzeigen.
Analytics – lesen	Aggregierte Kennzahlen der Organisation lesen: Nutzung, Signatur-Funnel und Akzeptanz. Niemals pro Person. Funktioniert nur, wenn Einstellungen → Richtlinien → KI-Zugriff auf Analytics dies ebenfalls erlaubt.
Webhooks – Signatur-Secret	Das Secret lesen und rotieren, mit dem wir die von uns gesendeten Webhooks signieren, damit das Zielsystem den Header X-AssinaJa-Signature prüfen kann. Nur an Webhook-Integrationen vergeben: Mit diesem Secret lassen sich Ereignisse signieren.
Vorlagenkatalog	Nur im Tarif Enterprise – siehe unten.

Versenden ist die gefährliche Berechtigung

Dokumente – versenden sendet E-Mails an die Unterzeichner und kann nicht rückgängig gemacht werden. Erstellen und Versenden sind bewusst getrennte Berechtigungen, damit eine Integration Entwürfe zur Prüfung durch einen Menschen vorbereiten kann, ohne sie je senden zu können. Vergeben Sie sie nur, wenn das System wirklich selbstständig senden soll.

Für einen KI-Assistenten: zunächst ohne die Berechtigung zum Versenden

Markieren Sie bei einer ersten MCP-Verbindung Vorlagen – lesen, Dokumente – lesen und Dokumente – erstellen, und lassen Sie Dokumente – versenden weg. Der Assistent bereitet alles vor und lässt das Dokument als Entwurf liegen; das Senden bleibt Ihre Aufgabe, in der Anwendung. Wenn Sie wissen, wie er sich verhält, können Sie die Berechtigung zum Versenden hinzufügen.

Dokumente – lesen gibt keinen Zugriff auf die Signaturlinks: Sie haben eine eigene Berechtigung, Dokumente – Signaturlinks, weil jeder, der einen Link hat, für den Unterzeichner unterschreibt. Vergeben Sie sie nur an eine Integration, die die Links wirklich zustellen muss.

Analytics – lesen braucht zusätzlich die Richtlinie der Organisation – siehe KI-Zugriff auf Analytics.

Der Zugriff auf den Vorlagenkatalog

Vorlagenkatalog – für andere Organisationen bereitstellen unterscheidet sich von den übrigen:

Ermöglicht anderen Organisationen, Dokumente aus dem Vorlagenkatalog dieser Organisation zu erzeugen (Header X-Api-Key-TemplateCatalog). Gewährt keinen weiteren Zugriff.

Er verwendet einen eigenen Header und gewährt nichts weiter. Er ist Nur im Tarif Enterprise verfügbar.

Ein Schlüssel mit dieser Berechtigung wird mit anderen Organisationen geteilt und darf daher keine Dokumente-Berechtigung haben: Die Plattform verweigert das Speichern in dieser Kombination. Verwenden Sie für den Katalog einen separaten Schlüssel.

Vorlagen über die öffentliche API: zwei Regeln

Es sind Regeln der öffentlichen API, und sie gelten für jeden Schlüssel, der Vorlagen abruft:

• Maßgeblich ist der Tarif der Organisation, die die Vorlage bereitstellt, nicht der des Aufrufers. Hat die Organisation, der der Katalog gehört, keine aktiven Vorlagen, antworten die fünf Endpunkte, die Vorlagen nutzen, mit 423 FEATURE_TEMPLATES_NOT_ENABLED.
• Entwürfe gibt es für die API nicht. Sie erscheinen nicht in der Auflistung, und die Abfrage der Details eines Entwurfs ergibt 404. Veröffentlichen Sie die Vorlage, bevor Sie sie integrieren.

Schlüssel verwalten

Die Liste zeigt Name, Schlüssel, Berechtigungen, Gültig bis, Status, Erstellt und Zuletzt verwendet – letztere mit Nie für einen Schlüssel, der sich nie authentifiziert hat. Diese Spalte ist der schnellste Weg, einen Schlüssel zu finden, den niemand nutzt.

Aktion	Wirkung
Bearbeiten	Name, Gültigkeit oder Berechtigungen ändern
Schlüssel rotieren	Ein neues Geheimnis für dieselbe Integration erzeugen – siehe unten
Sperren	„Ein gesperrter Schlüssel authentifiziert nicht mehr, bis er wieder aktiviert wird.“
Aktivieren	Einen gesperrten Schlüssel wieder aktivieren
Löschen	Endgültig

Der Status eines Schlüssels ist Aktiv, Gesperrt oder Abgelaufen.

Einen Schlüssel rotieren

Wenn Sie einen Schlüssel verloren haben oder vermuten, dass er offengelegt wurde, müssen Sie ihn nicht löschen und die Integration von Grund auf neu einrichten. Schlüssel rotieren öffnet Schlüssel rotieren – „Für diese Integration wird ein neuer Schlüssel erzeugt. Name, Berechtigungen, Gültigkeit und verbundene KI-Assistenten bleiben erhalten; nur das Geheimnis ändert sich.“ – und fragt, wann Der aktuelle Schlüssel funktioniert nicht mehr:

Option	Wann verwenden
Sofort – wählen Sie dies, wenn der Schlüssel offengelegt worden sein könnte	„Die Integration, die den aktuellen Schlüssel nutzt, kann sich ab dem Moment der Rotation nicht mehr authentifizieren.“
In 1 Stunde – Zeit für den Austausch im nutzenden System	Die Standardoption: Beide Schlüssel funktionieren eine Stunde lang.
In 24 Stunden	Dasselbe, mit einem Tag Spielraum.

Der neue Schlüssel wird nur ein einziges Mal angezeigt, wie beim Erstellen – Schlüssel rotiert, mit „Der vorherige Schlüssel funktioniert noch bis {Datum}. Ersetzen Sie ihn vorher in dem System, das ihn verwendet.“ oder, wenn Sie „Sofort“ gewählt haben, „Der vorherige Schlüssel funktioniert nicht mehr.“ In der Liste zeigt der Schlüssel dann Rotiert am {Datum} und, solange die Überschneidung dauert, „Der vorherige funktioniert bis {Datum}“.

Ein Abgelaufener Schlüssel lässt sich nicht rotieren – „Abgelaufen: Erstellen Sie einen neuen Schlüssel, statt diesen zu rotieren.“

Sperren Sie, bevor Sie löschen

Sperren lässt sich rückgängig machen, Löschen nicht – „kann nicht rückgängig gemacht werden – die Integration, die ihn nutzt, kann sich sofort nicht mehr authentifizieren.“ Wenn Sie vermuten, dass ein Schlüssel kompromittiert ist oder nicht genutzt wird, sperren Sie ihn und sehen Sie, was nicht mehr funktioniert. Wieder aktivieren können Sie ihn jederzeit.

Benachrichtigt werden, wenn etwas passiert

Damit Ihr System benachrichtigt wird, wenn mit einem Dokument etwas passiert, statt ständig nachzufragen, siehe Webhooks empfangen.

Siehe auch

• Webhooks empfangen
• Rollen und Berechtigungen – API-Schlüssel und Webhooks sind dem Inhaber vorbehalten; Integrationen und Speicher dem Inhaber und dem Administrator
• Richtlinien der Organisation konfigurieren