Vai al contenuto principale

​
Introduzione

Questa sezione fornisce la documentazione ufficiale per autenticarsi con la nostra API tramite Postman. Include istruzioni dettagliate sul processo di autenticazione, i metodi supportati e le migliori pratiche per garantire un accesso sicuro all’API.

​
🔑 Autenticazione

Per accedere a qualsiasi endpoint dell’API Lovi, devi prima autenticarti e ottenere un token di accesso utilizzando la tua email e password. Questo token deve poi essere incluso nell’header Authorization di tutte le richieste successive. Rotazione dei token: Raccomandiamo di ruotare periodicamente i token e di conservarli in modo sicuro.
Metodo: POST Formato: JSON

​
Endpoint

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

​
Parametri di query

ParametroObbligatorioValore fissoDescrizione
grant_typeSìpasswordIndica che stai utilizzando l’autenticazione tramite email e password. Questo è attualmente l’unico metodo supportato.

​
Header della richiesta

Informa il server del tipo di contenuto che stai inviando:
ChiaveValoreDescrizione
Content-Typeapplication/jsonIndica che il corpo della richiesta è in formato JSON.

​
Corpo della richiesta

Qui è dove fornisci le tue credenziali personali (la tua email e password): 
{
  "email": "your-email@example.com",
  "password": "your-secure-password"
}
Dovresti sostituire:
  • “your-email@example.com” con il tuo indirizzo email effettivo.
  • “your-secure-password” con la tua password.

​
Risposta

Il server risponderà con un token che dovrai utilizzare per autenticarti nelle future chiamate API. La risposta avrà questo aspetto: 
{
    "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
    }
}
⚠️ Salva il tuo access_token — lo userai per interagire con il resto dell’API.

​
🧭 Recupera le chiavi API dell’azienda

Metodo: POST Formato: JSON

​
Endpoint

POST https://cloud.lovi.ai/functions/v1/api_keys
Header
ParametroEsempioObbligatorioDescrizione
AuthorizationBearer your-access-tokenSìQuesto header è utilizzato per autenticare la richiesta. Contiene un token Bearer ricevuto dopo il login.

​
Risposta

Ogni oggetto all’interno dell’array validApiKeys rappresenta una chiave API associata a un’azienda specifica. I campi inclusi sono:
  • company_id: Identificatore unico dell’azienda proprietaria della chiave API.
  • key: La chiave API stessa, utilizzata per autenticare le richieste.
  • is_active: Valore booleano che indica se la chiave è attualmente attiva (true) o inattiva (false).
  • last_used: Timestamp dell’ultima volta che la chiave è stata utilizzata. Se la chiave non è mai stata usata, il valore sarà null.
  • company_name: Nome dell’azienda associata alla chiave API, utile per la visualizzazione nelle interfacce o nei log.
Ecco un esempio: 
{
    "validApiKeys": [
        {
            "company_id": "your_company_id",
            "key": "your_key",
            "is_active": true,
            "last_used": null,
            "company_name": "your_company_name"
        }
    ]
}

​
⚠️ Nessuna chiave API trovata

Se la risposta restituisce un array validApiKeys vuoto, significa che non sono ancora state create chiavi API per la tua azienda. Esempio: 
{
    "validApiKeys": []
}
In questo caso, devi andare nella Dashboard Admin e creare una nuova chiave API per la tua azienda.

Configurazione delle chiavi API dalla 'Dashboard Admin'

In questa sezione, vedrai come configurare il profilo e anche come configurare la chiave API dal pannello.
🧭 Importante: Senza una chiave API valida e attiva, non potrai autenticarti a livello aziendale né eseguire operazioni protette.
Una volta che la chiave API è stata creata e attivata, apparirà nell’array validApiKeys e potrà essere utilizzata per generare un token a livello aziendale.

​
🔁 Token per azienda

Una volta identificata l’azienda con cui vuoi lavorare, devi autenticarti nuovamente per generare un token a livello aziendale. Questo è di solito necessario per azioni protette come l’invio di notifiche o il caricamento di media. Utilizzerai la key precedentemente recuperata nei tuoi parametri di query o header, a seconda dell’endpoint.