Autenticación - Lovi AI Documentation

Introducción

Esta sección proporciona la documentación oficial para autenticarse con nuestra API a través de Postman. Incluye instrucciones detalladas sobre el proceso de autenticación, los métodos admitidos y las mejores prácticas para garantizar un acceso seguro a la API.

🔑 Autenticación

Para acceder a cualquier endpoint de la API de Lovi, primero debes autenticarte y obtener un token de acceso usando tu email y contraseña. Este token debe incluirse en el encabezado Authorization de todas las solicitudes posteriores. Rotación de Tokens: Recomendamos rotar los tokens periódicamente y almacenarlos de forma segura.

Método: POST Formato: JSON

Endpoint

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

Parámetros de Consulta

Parámetro	Requerido	Valor Fijo	Descripción
`grant_type`	Sí	`password`	Indica que estás usando autenticación mediante email y contraseña. Este es actualmente el único método admitido.

Encabezados de la Solicitud

Informa al servidor sobre el tipo de contenido que estás enviando:

Clave	Valor	Descripción
`Content-Type`	`application/json`	Indica que el cuerpo de la solicitud está en formato JSON.

Cuerpo de la Solicitud

Aquí proporcionas tus credenciales personales (tu email y contraseña):

{
  "email": "tu-email@ejemplo.com",
  "password": "tu-contraseña-segura"
}

Debes reemplazar:

“tu-email@ejemplo.com” con tu dirección de email real.
“tu-contraseña-segura” con tu contraseña.

Respuesta

El servidor responderá con un token que necesitarás para autenticarte en futuras llamadas a la API. La respuesta tendrá este aspecto:

{
    "access_token": "tu-token-de-acceso",
    "token_type": "bearer",
    "expires_in": 3600,
    "expires_at": 1744196340,
    "refresh_token": "bNYf6m7S7dFjfHCFTob2zg",
    "user": {
        "id": "3b601fa8-49fd-4a8c-af8c-b30601410975",
        "aud": "authenticated",
        "role": "authenticated",
        "email": "tu-email@ejemplo.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": "Tu-Empresa"
        },
        "identities": [
            {
                "identity_id": "23b66c68-ce37-4483-8470-67e08e21a61e",
                "id": "3b601fa8-49fd-4a8c-af8c-b30601410975",
                "user_id": "3b601fa8-49fd-4a8c-af8c-b30601410975",
                "identity_data": {
                    "email": "tu-email@ejemplo.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": "tu-email@ejemplo.com"
            }
        ],
        "created_at": "2025-01-16T18:45:09.956743Z",
        "updated_at": "2025-04-09T09:59:00.192243Z",
        "is_anonymous": false
    }
}

⚠️ Guarda tu access_token — lo usarás para interactuar con el resto de la API.

🧭 Recuperar Claves API de la Empresa

Método: POST Formato: JSON

Endpoint

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

Encabezados

Parámetro	Ejemplo	Requerido	Descripción
Authorization	Bearer tu-token-de-acceso	Sí	Este encabezado se usa para autenticar la solicitud. Contiene un token Bearer recibido después de iniciar sesión.

Respuesta

Cada objeto dentro del array validApiKeys representa una clave API asociada a una empresa específica. Los campos incluidos son:

company_id: Identificador único de la empresa propietaria de la clave API.
key: La clave API en sí, utilizada para autenticar solicitudes.
is_active: Valor booleano que indica si la clave está actualmente activa (true) o inactiva (false).
last_used: Marca de tiempo de la última vez que se usó la clave. Si la clave nunca se ha usado, el valor será null.
company_name: Nombre de la empresa asociada a la clave API, útil para mostrar en interfaces o registros.

Aquí hay un ejemplo:

{
    "validApiKeys": [
        {
            "company_id": "tu_id_empresa",
            "key": "tu_clave",
            "is_active": true,
            "last_used": null,
            "company_name": "nombre_tu_empresa"
        }
    ]
}

⚠️ No se Encontraron Claves API

Si la respuesta devuelve un array validApiKeys vacío, significa que aún no se han creado claves API para tu empresa. Ejemplo:

{
    "validApiKeys": []
}

En este caso, debes ir al Panel de Administración y crear una nueva clave API para tu empresa.

Configurar claves API desde el 'Panel de Administración'

En esta sección verás cómo configurar el perfil y también cómo configurar la Clave API desde el panel.

🧭 Importante: Sin una clave API válida y activa, no podrás autenticarte a nivel de empresa ni realizar operaciones seguras.

Una vez que la clave API se crea y está activa, aparecerá en el array validApiKeys y podrá usarse para generar un token a nivel de empresa.

🚫 Acceso a la API Denegado (403 Forbidden)

Si tu empresa ha deshabilitado el acceso a la API, el servidor devolverá un estado 403 Forbidden. Esto ocurre cuando apiAccess está configurado como false para una o más empresas asociadas a tu cuenta. Ejemplo:

{
    "success": false,
    "message": "API access denied for some companies",
    "deniedCompanies": [
        {
            "company_id": "tu_id_empresa",
            "company_name": "nombre_tu_empresa",
            "access": false
        }
    ]
}

En este caso, debes asegurarte de que el acceso a la API esté habilitado para tu empresa en la configuración antes de poder recuperar sus claves.

🔁 Token por Empresa

Una vez que identificas con qué empresa quieres trabajar, debes autenticarte de nuevo para generar un token a nivel de empresa. Esto generalmente es necesario para acciones seguras como enviar notificaciones o subir archivos multimedia. Usarás la key recuperada anteriormente en tus parámetros de consulta o encabezados, según el endpoint.

​Introducción

​🔑 Autenticación

​Endpoint

​Parámetros de Consulta

​Encabezados de la Solicitud

​Cuerpo de la Solicitud

​Respuesta

​🧭 Recuperar Claves API de la Empresa

​Endpoint

​Respuesta

​⚠️ No se Encontraron Claves API

Configurar claves API desde el 'Panel de Administración'

​🚫 Acceso a la API Denegado (403 Forbidden)

​🔁 Token por Empresa

Introducción

🔑 Autenticación

Endpoint

Parámetros de Consulta

Encabezados de la Solicitud

Cuerpo de la Solicitud

Respuesta

🧭 Recuperar Claves API de la Empresa

Endpoint

Respuesta

⚠️ No se Encontraron Claves API

🚫 Acceso a la API Denegado (403 Forbidden)

🔁 Token por Empresa