OpenAPI Introduction

Welcome to Lovrabet OpenAPI! This is a secure and efficient data interface service that allows you to programmatically access business data in the Lovrabet platform.

Beta Phase

OpenAPI is currently in beta phase and only available to selected partners. Please contact your account manager to enable access.

What is Lovrabet OpenAPI?

Lovrabet OpenAPI is a data interface service designed for enterprise applications, using HMAC-SHA256 signature-based authentication to ensure the security and integrity of data transmission.

Core Features

🔐 Secure Authentication - HMAC-SHA256 signature-based with multiple authentication modes
🚀 Ready to Use - Official SDK automatically handles authentication, signing, and token management
🌐 Multi-Environment Support - Supports server-side (Node.js) and browser-side
📊 Powerful Queries - Supports pagination, sorting, conditional filtering, and more
📝 TypeScript - Complete type definitions and intelligent hints
🛡️ Permission Isolation - Application-level data access control

Three Authentication Modes

Based on runtime environment and usage scenarios, OpenAPI provides three authentication methods:

1. Server-Side Mode - Using accessKey

Use Case: Node.js server-side, SSR (Server-Side Rendering), API routes

Use accessKey to generate tokens in real-time without pre-generation:

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY, // ✅ Read from environment variables
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// Call directly, SDK automatically handles authentication
const users = await client.models.users.filter();

2. Browser Token Mode - Pre-generated Token

Use Case: Browser-side public data access, unauthenticated users

Server-side generates token, browser-side uses it:

// Step 1: Server-side generates token (e.g., Next.js API route)
import { generateOpenApiToken } from "@lovrabet/sdk";

export async function GET() {
  const result = await generateOpenApiToken({
    appCode: "your-app-code",
    datasetCode: "ds-001",
    accessKey: process.env.LOVRABET_ACCESS_KEY,
  });

  return Response.json(result); // { token, timestamp, expiresAt }
}

// Step 2: Browser uses token
const { token, timestamp } = await fetch("/api/token").then((r) => r.json());

const client = createClient({
  appCode: "your-app-code",
  token: token,
  timestamp: timestamp,
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

Use Case: Authenticated users accessing private data

No authentication information needed, automatically uses browser cookies:

const client = createClient({
  appCode: "your-app-code",
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// Request automatically carries user's login cookie
const users = await client.models.users.filter();

How to Choose Authentication Mode?

Server-side? → Use accessKey mode
Browser + Public Data? → Use pre-generated token mode
Browser + Authenticated User? → Use cookie mode

Use Cases

1. Data Integration and Synchronization

Integrate Lovrabet platform business data into your enterprise systems:

BI Reporting Systems - Regularly sync data to data warehouse for management reports
ERP Integration - Interface with enterprise ERP systems for data interoperability
Data Hub - Use as data source for enterprise data hubs

2. Custom Application Development

Build your own applications based on Lovrabet data:

Mobile Applications - Provide data interface support for mobile platforms
WeChat Mini Programs - Rapidly develop lightweight business applications
Web Applications - Build customized web management systems

3. Data Analysis and Mining

Leverage OpenAPI for deep data analysis:

Real-time Monitoring - Build business data real-time monitoring dashboards
Data Analysis - Export data for statistical analysis and mining
Trend Prediction - Predict business trends based on historical data

4. Automated Workflows

Achieve business process automation through API:

Scheduled Tasks - Automatically execute data queries and export tasks
Event Triggers - Trigger business processes based on data changes
Batch Processing - Efficiently process large-scale data queries

Current Capabilities

Feature Scope

OpenAPI currently provides complete CRUD operations (query, create, update) with application-level data access. Delete operation is temporarily only available in WebAPI (cookie authentication) mode.

Available Endpoints

OpenAPI provides the following endpoints with base URL: https://runtime.lovrabet.com

Endpoint	HTTP Path	SDK Method	Description
Batch Query	`POST /openapi/data/get-list`	`getList(params?, sortList?)`	Paginated data query with filtering and multi-field sorting
Single Query	`POST /openapi/data/get-one`	`getOne(id)`	Retrieve complete details of a single record by ID
Create Data	`POST /openapi/data/create`	`create(data)`	Create new data record
Update Data	`POST /openapi/data/update`	`update(id, data)`	Update existing data record (supports partial updates)

Complete API Specification

For detailed endpoint parameters and request/response formats, please refer to the API Reference documentation.

API Usage Example

// Batch query (supports pagination, sorting, filtering)
const users = await client.models.users.filter(
  {
    currentPage: 1,
    pageSize: 20,
    status: "active", // Conditional filtering
  },
  [
    { priority: SortOrder.DESC }, // Multi-field sorting
    { createTime: SortOrder.DESC },
  ]
);

// Query single record
const user = await client.models.users.getOne(123);

// Create data
const newUser = await client.models.users.create({
  name: "John Doe",
  email: "john@example.com",
});

// Update data
const updated = await client.models.users.update(123, {
  status: "inactive",
});

Authentication Method

All OpenAPI requests require HMAC-SHA256 signature authentication, with authentication information passed through HTTP headers:

Header Name	Description	Example
`X-Time-Stamp`	Request timestamp (milliseconds)	1758903130713
`X-App-Code`	Application code	app-c2dd52a2
`X-Dataset-Code`	Dataset code	0fefba76fe29440194841f4825df53ff
`X-Token`	HMAC-SHA256 signature	jdqqGtzecF2I6FIW...

The SDK automatically handles all authentication details without manual header addition.

Coming Soon

⏳ Delete Operation - delete() method in OpenAPI mode (currently only supported in WebAPI mode)
⏳ Webhook Notifications - Real-time push notifications for data changes
⏳ Batch Operations - Support for batch create, update, import and export
⏳ File Upload - Support for file field upload and management

Response Structure

All OpenAPI endpoints follow a unified response format.

getList Response Format

{
  "success": true,
  "msg": "Operation successful",
  "data": {
    "paging": {
      "pageSize": 10,
      "totalCount": 100,
      "currentPage": 1
    },
    "tableData": [
      {
        "id": "123",
        "name": "Sample Data",
        "status": "active",
        "gmt_create": "2024-01-01 12:00:00"
      }
    ],
    "tableColumns": [
      {
        "title": "ID",
        "dataIndex": "id"
      },
      {
        "title": "Name",
        "dataIndex": "name"
      }
    ]
  }
}

Fixed Field Descriptions:

paging - Pagination information (total count, current page, page size)
tableData - Actual data list array
tableColumns - Table column definition metadata for dynamic UI construction

Security Best Practices

Important Security Notice

Never expose accessKey in browser-side code!

❌ Wrong Approach:

// Dangerous! Will expose secret key
const client = createClient({
  accessKey: "sk_live_xxx", // ❌ Never do this!
});

✅ Correct Approach:

// Server-side: Use environment variables
const client = createClient({
  accessKey: process.env.LOVRABET_ACCESS_KEY,
});

// Browser: Use pre-generated token
const { token } = await fetch("/api/token").then((r) => r.json());
const client = createClient({ token });

Security Mechanisms

Token Expiration - Each token expires after 10 minutes
Signature Verification - All requests must carry correct HMAC-SHA256 signature
HTTPS Enforcement - Production environment enforces HTTPS encrypted transmission
Application Isolation - Each application can only access authorized datasets
Environment Variables - Sensitive information stored in environment variables, not committed to code repository

Data Permissions

Application Isolation - Each application can only access authorized datasets
Field Permissions - Supports field-level access control
Row-Level Permissions - Supports data row-level filtering

SDK Support

To simplify development, we provide an official SDK:

npm install @lovrabet/sdk
# or
bun add @lovrabet/sdk

SDK Advantages:

✅ Automatic authentication and signing
✅ Automatic token lifecycle management
✅ Complete TypeScript type support
✅ Unified error handling

Resource Links:

Onboarding Process

1. Apply for Access

Please contact your account manager and provide the following information:

Company name and business scenario description
Estimated call volume and concurrency requirements
List of datasets to be accessed
Technical contact information

2. Obtain Credentials

After approval, you will receive:

App Code - Unique application identifier
Access Key - Access key (please keep it secure)
Dataset Codes - List of authorized datasets

Technical Specifications

API Specifications

Protocol: HTTPS
Method: POST
Encoding: UTF-8
Format: JSON

Environment Information

Environment	Domain
Production	`https://runtime.lovrabet.com`

Next Steps

Ready to start using OpenAPI? We recommend learning in this order:

Quick Start - Complete your first API call in 5 minutes
Authentication Guide - Deep dive into the three authentication modes and token management
API Reference - View complete endpoint documentation and advanced usage

Start with Quick Start

If this is your first time, we recommend going directly to the Quick Start documentation to get hands-on experience through practical examples.

Support and Feedback

For technical support or any questions, please contact us through:

📧 Technical Support: Contact your account manager for technical support information
📚 Developer Documentation: Continuously updated
💬 Online Customer Service: Monday-Friday 9:00-18:00

What is Lovrabet OpenAPI?​

Core Features​

Three Authentication Modes​

1. Server-Side Mode - Using accessKey​

2. Browser Token Mode - Pre-generated Token​

3. Browser Cookie Mode - Using User Login State​

Use Cases​

1. Data Integration and Synchronization​

2. Custom Application Development​

3. Data Analysis and Mining​

4. Automated Workflows​

Current Capabilities​

Available Endpoints​

API Usage Example​

Authentication Method​

Coming Soon​

Response Structure​

getList Response Format​

Security Best Practices​

Security Mechanisms​

Data Permissions​

SDK Support​

Onboarding Process​

1. Apply for Access​

2. Obtain Credentials​

Technical Specifications​

API Specifications​

Environment Information​

Next Steps​

Support and Feedback​