Authentifizierung - Lovi AI Documentation

Einführung

Dieser Abschnitt bietet die offizielle Dokumentation zur Authentifizierung mit unserer API über Postman. Er enthält detaillierte Anweisungen zum Authentifizierungsprozess, unterstützten Methoden und Best Practices zur Gewährleistung eines sicheren Zugriffs auf die API.

🔑 Authentifizierung

Um auf einen Lovi-API-Endpunkt zuzugreifen, müssen Sie sich zunächst authentifizieren und ein Zugriffstoken mit Ihrer E-Mail und Ihrem Passwort erhalten. Dieses Token muss dann im Authorization-Header aller nachfolgenden Anfragen enthalten sein. Token-Rotation: Wir empfehlen, Tokens regelmäßig zu rotieren und sie sicher zu speichern.

Methode: POST Format: JSON

Endpunkt

POST https://cloud.lovi.ai/functions/v1/auth?grant_type=password

Query-Parameter

Parameter	Pflicht	Fester Wert	Beschreibung
`grant_type`	Ja	`password`	Gibt an, dass Sie die Authentifizierung per E-Mail und Passwort verwenden. Dies ist derzeit die einzige unterstützte Methode.

Request-Header

Informieren Sie den Server über den Typ des Inhalts, den Sie senden:

Schlüssel	Wert	Beschreibung
`Content-Type`	`application/json`	Gibt an, dass der Request-Body im JSON-Format ist.

Request-Body

Hier geben Sie Ihre persönlichen Anmeldedaten (Ihre E-Mail und Ihr Passwort) an:

{
  "email": "ihre-email@beispiel.de",
  "password": "ihr-sicheres-passwort"
}

Ersetzen Sie:

“ihre-email@beispiel.de” durch Ihre tatsächliche E-Mail-Adresse.
“ihr-sicheres-passwort” durch Ihr Passwort.

Antwort

Der Server antwortet mit einem Token, das Sie für die Authentifizierung bei zukünftigen API-Aufrufen benötigen. Die Antwort sieht so aus:

{
    "access_token": "your-access-token",
    "token_type": "bearer",
    "expires_in": 3600,
    "expires_at": 1744196340,
    "refresh_token": "bNYf6m7S7dFjfHCFTob2zg",
    "user": {
        "id": "3b601fa8-49fd-4a8c-af8c-b30601410975",
        "aud": "authenticated",
        "role": "authenticated",
        "email": "your-email@example.com",
        "email_confirmed_at": "2025-01-16T18:45:09.995114Z",
        "phone": "",
        "confirmed_at": "2025-01-16T18:45:09.995114Z",
        "last_sign_in_at": "2025-04-09T09:59:00.18987884Z",
        "app_metadata": {
            "provider": "email",
            "providers": [
                "email"
            ]
        },
        "user_metadata": {
            "email_verified": true,
            "name": "Your-Company"
        },
        "identities": [
            {
                "identity_id": "23b66c68-ce37-4483-8470-67e08e21a61e",
                "id": "3b601fa8-49fd-4a8c-af8c-b30601410975",
                "user_id": "3b601fa8-49fd-4a8c-af8c-b30601410975",
                "identity_data": {
                    "email": "your-email@example.com",
                    "email_verified": false,
                    "phone_verified": false,
                    "sub": "3b601fa8-49fd-4a8c-af8c-b30601410975"
                },
                "provider": "email",
                "last_sign_in_at": "2025-01-16T18:45:09.985377Z",
                "created_at": "2025-01-16T18:45:09.985932Z",
                "updated_at": "2025-01-16T18:45:09.985932Z",
                "email": "your-email@example.com"
            }
        ],
        "created_at": "2025-01-16T18:45:09.956743Z",
        "updated_at": "2025-04-09T09:59:00.192243Z",
        "is_anonymous": false
    }
}

⚠️ Speichern Sie Ihr access_token — Sie werden es benötigen, um mit dem Rest der API zu interagieren.

🧭 Unternehmens-API-Keys abrufen

Methode: POST Format: JSON

Endpunkt

POST https://cloud.lovi.ai/functions/v1/api_keys

Header

Parameter	Beispiel	Pflicht	Beschreibung
Authorization	Bearer your-access-token	Ja	Dieser Header wird zur Authentifizierung der Anfrage verwendet. Er enthält ein Bearer-Token, das nach der Anmeldung erhalten wurde.

Antwort

Jedes Objekt innerhalb des validApiKeys-Arrays repräsentiert einen API-Key, der einem bestimmten Unternehmen zugeordnet ist. Die enthaltenen Felder sind:

company_id: Eindeutiger Bezeichner des Unternehmens, dem der API-Key gehört.
key: Der API-Key selbst, der zur Authentifizierung von Anfragen verwendet wird.
is_active: Boolean-Wert, der angibt, ob der Key derzeit aktiv (true) oder inaktiv (false) ist.
last_used: Zeitstempel der letzten Verwendung des Keys. Wenn der Key nie verwendet wurde, ist der Wert null.
company_name: Name des Unternehmens, das dem API-Key zugeordnet ist, nützlich für die Anzeige in Oberflächen oder Logs.

Hier ist ein Beispiel:

{
    "validApiKeys": [
        {
            "company_id": "your_company_id",
            "key": "your_key",
            "is_active": true,
            "last_used": null,
            "company_name": "your_company_name"
        }
    ]
}

⚠️ Keine API-Keys gefunden

Wenn die Antwort ein leeres validApiKeys-Array zurückgibt, bedeutet dies, dass noch keine API-Keys für Ihr Unternehmen erstellt wurden. Beispiel:

{
    "validApiKeys": []
}

In diesem Fall müssen Sie zum Admin-Dashboard gehen und einen neuen API-Key für Ihr Unternehmen erstellen.

API-Keys über das 'Admin-Dashboard' konfigurieren

In diesem Abschnitt erfahren Sie, wie Sie das Profil konfigurieren und auch wie Sie den API-Key über das Dashboard konfigurieren.

🧭 Wichtig: Ohne einen gültigen und aktiven API-Key können Sie sich nicht auf Unternehmensebene authentifizieren oder gesicherte Operationen durchführen.

Sobald der API-Key erstellt und aktiv ist, erscheint er im validApiKeys-Array und kann zur Generierung eines Tokens auf Unternehmensebene verwendet werden.

🔁 Token pro Unternehmen

Sobald Sie identifiziert haben, mit welchem Unternehmen Sie arbeiten möchten, müssen Sie sich erneut authentifizieren, um ein Token auf Unternehmensebene zu generieren. Dies ist normalerweise für gesicherte Aktionen wie das Senden von Benachrichtigungen oder das Hochladen von Medien erforderlich. Sie verwenden den zuvor abgerufenen key in Ihren Query-Parametern oder Headern, je nach Endpunkt.

API-Dokumentation

Documentation Index

​Einführung