Authentication

Official documentation for authenticating with our API

Introduction

This section provides the official documentation for authenticating with our API via Postman. It includes detailed instructions on the authentication process, supported methods, and best practices to ensure secure access to the API.

🔑 Authentication

To access any Lovi API endpoint, you must first authenticate and obtain an access token using your email and password. This token must then be included in the Authorization header of all subsequent requests.

Token Rotation: We recommend periodically rotating tokens and storing them securely.

Method: POST Format: JSON

Endpoint

POST https://cloud.lovi.ai/auth/v1/token

Query Parameters

Parameter	Required	Fixed Value	Description
grant_type	Yes	password	Indicates that you’re using authentication via email and password.

Request Headers

Inform the server of the type of content you are sending:

Key	Value	Description
Content-Type	application/json	Indicates that the request body is in JSON format.

Request Body

This is where you provide your personal credentials (your email and password):

{
  "email": "[e-mail]",
  "password": "your-secure-password"
}

You should replace:

• “[e-mail]” with your actual email address.
• “your-secure-password” with your password.

Response

The server will respond with a token that you will need to authenticate in future API calls. The response will look like this:

{
    "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": "[e-mail]",
        "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": "[e-mail]",
                    "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": "[e-mail]"
            }
        ],
        "created_at": "2025-01-16T18:45:09.956743Z",
        "updated_at": "2025-04-09T09:59:00.192243Z",
        "is_anonymous": false
    }
}

⚠️ Save your access_token — you’ll use it to interact with the rest of the API.

---

🧭 Retrieve Company API Keys

Method: POST Format: JSON

Endpoint

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

Headers

Parameter	Example	Required	Description
Authorization	Bearer your-access-token	Yes	This header is used for authenticating the request. It contains a Bearer token received after logging in.

Response

Each object within the validApiKeys array represents an API key associated with a specific company. The fields included are:

• company_id: Unique identifier of the company that owns the API key.

• key: The API key itself, used to authenticate requests.

• is_active: Boolean value indicating whether the key is currently active (true) or inactive (false).

• last_used: Timestamp of the last time the key was used. If the key has never been used, the value will be null.

• company_name: Name of the company associated with the API key, useful for display in interfaces or logs.

Here’s an example:

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

Use the key provided in the response to authenticate future requests and perform operations on behalf of the specified company.

📝Each company will have a unique access key. You must use the correct key depending on which company you’re interacting with.

🔁 Token per Company

Once you identify which company you want to work with, you must authenticate again to generate a company-level token. This is usually required for secured actions like sending notifications or uploading media.

You will use the previously retrieved key in your query parameters or headers, depending on the endpoint.