Documentation

Getting Started

Welcome to Igniral

Igniral simplifies backend development by allowing you to design, deploy, and manage production-ready REST APIs visually. Whether you are building a prototype or a scalable microservice, Igniral handles the infrastructure so you can focus on data and logic.

How it Works

The workflow is designed to be intuitive:

1. Define: Create an Application to group your resources.
2. Design: Use the Schema Builder to model your data (e.g., Users, Products).
3. Deploy: Your endpoints are instantly live and ready to use.
4. Secure: Control who can access your data with Access Control.

Applications

What is an Application?

An Application serves as a namespace or container for your APIs. It groups related schemas and endpoints together. For example, you might have separate applications for "E-commerce Store," "Inventory Management," and "User Auth."

Configuration Options

• Name: The unique identifier for your app. This will be part of your API URL.
• Version: Helps you manage API lifecycle (e.g., v1, v2). Changing this allows you to release updates without breaking existing clients.
• Private Mode:
  • No (Public): Endpoints are open to the world. Good for public data or testing.
  • Yes (Private): Requires a valid JWT Bearer token for access.
• Status: "Disabled" applications will reject all incoming requests immediately.

Data Export & Migration

You can export the complete data of any application as a downloadable JSON file directly from the Applications table in your dashboard. Click the download button in the Actions column.

What's included

• Application metadata: Name, version, subdomain, privacy settings, status, and AI-generated context.
• Endpoint definitions: Paths, JSON schemas, security policies, allowed HTTP methods, and documentation.
• All data records: Every record stored across all JSON endpoints, streamed progressively to avoid memory issues.
• File endpoint metadata: File names, content types, and sizes (binary files are not included in the export).
• Export summary: Total endpoints, record counts (JSON vs File), and share statistics.

Security guarantees

• Only one export at a time per user account — prevents system overload and DoS.
• All write operations (POST, PUT, DELETE) are temporarily paused during the export to guarantee a consistent snapshot.
• The export lock auto-releases after 10 minutes if the download is interrupted.
• Strict tenant isolation — you can only export applications you own.

Schema Builder

Designing Your Data

The Schema Builder is where you define the structure of your database objects. Igniral uses this definition to validate incoming data and generate HTML documentation.

Smart Type Inference

When adding attributes, Igniral automatically suggests the appropriate data type based on the name:

• email → string (format: email)
• created_at, dob → string (format: date-time)
• is_active, has_access → boolean
• price, rating → number
• count, age → integer

Advanced Configuration

For each attribute, you can configure:

• Required: Marks the field as mandatory. Requests missing this field will fail with a 400 error.
• Unique: Ensures no two records have the same value (e.g., for Usernames or SKUs).
• Array/Object: Create complex nested structures by selecting these types.

File Uploads

Purpose

The File Uploads section allows you to manage files that have been uploaded to your application's file endpoints. You can view, download, and delete files stored in your API.

Getting Started

To manage files, follow these steps:

• Select Application: Choose the application containing the files you want to manage.
• Select Endpoint: Choose a file endpoint to view its uploaded files.

Uploading Files

Once you've selected an application and endpoint, click the Upload File button. You can:

• Drag and drop files directly into the upload zone.
• Click to browse and select files from your computer.

Managing Files

For each uploaded file, you can:

• View: Click on the file name to open it in a new tab.
• Download: Click the download button to save the file locally.
• Delete: Click the trash icon to permanently remove the file.

API Metrics

Monitoring Performance

Keep track of your API's health and usage patterns. Metrics are aggregated in real-time.

Key Indicators

• Avg Latency: The time it takes for the server to process a request. Consistently high latency (>500ms) may indicate inefficient queries or heavy load.
• Error Rate (4xx/5xx):
  • 4xx (Client Error): Usually means invalid data sent by the user (e.g., missing fields).
  • 5xx (Server Error): Indicates a problem on the Igniral platform or database connectivity.

Usage Trends

Use the "Requests Over Time" chart to identify peak usage hours. The "Top Endpoints" list helps you optimize the most critical parts of your application.

Access Control

Securing Your Private Apps

When an application is set to Private, only authenticated users with the correct permissions can access it. Access Control is where you manage these entities.

User Management

Create accounts for the actual consumers of your API (e.g., mobile app users, frontend clients). You can suspend users instantly to revoke their access without deleting their data.

Role-Based Access Control (RBAC)

Roles are collections of permissions that can be assigned to users. This allows for flexible security policies:

• Admin Role: Might have GET, POST, PUT, DELETE on all resources.
• Viewer Role: Might only have GET permissions.
• Editor Role: Might have GET and PUT, but not DELETE.

Users obtain an access token by logging in via the /auth/login endpoint of your application. This token must be sent in the Authorization: Bearer <token> header of subsequent requests.

Data Encryption

Overview

Igniral provides built-in encryption at rest to protect sensitive data stored in your endpoints. Encryption is applied automatically — no code changes needed on your side. Your data is encrypted before it is saved and decrypted transparently when you read it back through the API.

How It Works

Igniral applies field-level encryption to protect sensitive values within your JSON records using AES-256-GCM, a military-grade authenticated encryption algorithm. You choose which fields are sensitive (e.g., ssn, medical_record, credit_card) by marking them in the schema, and Igniral encrypts only those fields — non-sensitive fields remain in plain text so they can be queried and filtered normally.

For fields that need to be searchable even when encrypted, Igniral automatically generates blind indexes (HMAC-SHA256). This lets you search by exact value without ever exposing the plaintext.

File Storage

Uploaded files pass through an antimalware scanning pipeline before becoming available. Files land in a quarantine bucket, are scanned by ClamAV, and only clean files are moved to the production bucket. At-rest encryption for stored objects is handled by the cloud provider using standard managed keys.

Key Isolation & Derivation

Igniral derives a unique encryption key for each tenant internally from a master key using HKDF (HMAC-based Key Derivation Function). Keys are never exposed to end users. This ensures:

• Tenant isolation: Each tenant's key is mathematically independent from any other tenant's key.
• Zero plaintext key storage: Encryption keys are derived on-the-fly and cached only in memory — they are never stored in the database.

Automatic Key Rotation

Igniral supports seamless key rotation without downtime. A Cloud Scheduler job triggers the rotation automatically every 180 days:

1. A new key version is activated.
2. All existing encrypted data is re-encrypted record by record with the new key.
3. Old key versions are retained temporarily for backward compatibility during the transition.
4. An audit log records every rotation event for compliance.

Google Social Login

Overview

Allow your application's end users to sign in with their Google account. Igniral acts as a secure intermediary — the entire OAuth exchange happens server-side. You do not need a Google Client ID or any OAuth credentials.

Configuration

1. Go to Applications in the Dashboard and edit your app.
2. Enable Google Sign-In.
3. Select a Default Role for new social login users.
4. Enter your Redirect URI — the URL where users land after authentication (e.g., https://miapp.com/auth/callback).
5. Click Save.

Integration

In your frontend, add a link or button that redirects users to the authorize URL (shown in the Dashboard after saving). This URL must be opened in a browser — it is a redirect-based OAuth flow, not a REST API.

<a href="https://auth.igniral.io/api/oauth/google/authorize?applicationId=YOUR_APP_ID">
  Sign in with Google
</a>

After authentication, the user is redirected to your Redirect URI with query parameters:

https://miapp.com/callback?token=eyJhbG...&refresh_token=AMf-vB...&email=user@example.com

Using the Token

Use the token value as a Bearer token for all API requests:

curl https://{your-subdomain}.igniral.io/api/products \
  -H "Authorization: Bearer eyJhbG..."

Two-Factor Authentication (2FA)

Overview

Add TOTP-based two-factor authentication to your application's user accounts. When 2FA is enabled, users must provide a 6-digit code from an authenticator app (Google Authenticator, Authy, Microsoft Authenticator, etc.) during login.

Self-Service Setup (API)

Users manage their own 2FA through these endpoints:

Login Flow with 2FA

When a user with 2FA enabled calls /api/oauth/login, the login returns a challenge instead of tokens:

// Step 1: Login → returns challengeId
POST /api/oauth/login
{ "email": "user@example.com", "password": "..." }

→ { "twoFactorRequired": true, "challengeId": "a1b2c3d4-..." }

// Step 2: Verify 2FA → returns tokens
POST /api/oauth/verify-2fa
{ "challengeId": "a1b2c3d4-...", "totpCode": "123456" }

→ { "accessToken": "eyJhbG...", "refreshToken": "AMf-vB...", "expiresIn": "3600" }

Account Settings

Security Best Practices

Password Policy: Your dashboard password protects all your applications. We enforce a strong password policy (min 12 chars, mixed case, numbers, symbols) to prevent unauthorized access.

Two-Factor Authentication (2FA): We strongly recommend enabling 2FA. This adds a second step to the login process, requiring a time-based code from an app like Google Authenticator or Authy. Even if your password is compromised, your account remains secure. Important: Save your recovery codes in a safe place when enabling 2FA; they are the only way to recover access if you lose your phone.

Data Management

Subscriptions

Plans & Pricing

Igniral offers flexible plans designed to grow with your needs. You can upgrade or downgrade your plan at any time from the dashboard.

Billing & Management

• Billing Cycle: Subscriptions are billed monthly on the date you sign up.
• Upgrading: Changes take effect immediately. You will be charged the prorated difference for the current month.
• Downgrading: Changes take effect at the start of the next billing cycle. You retain your current plan features until then.
• Cancellation: You can cancel your subscription at any time. Your access continues until the end of the billing period.

API Reference

OpenAPI / Swagger Documentation

Each application you create in Igniral automatically generates a complete OpenAPI (Swagger) specification. This documentation is always in sync with your schema definitions.

Accessing Your API Docs

You can access the Swagger UI for your application from the dashboard:

1. Navigate to your Application in the dashboard
2. Click the API Docs button in the application card
3. Explore endpoints, try requests, and download the OpenAPI spec

Features

• Interactive Testing: Try API calls directly from the documentation
• Request/Response Examples: See sample payloads for each endpoint
• Schema Definitions: View the complete data model for your resources
• Authentication: Configure Bearer tokens for private endpoints

AI Agent (MCP)

Building with AI

Igniral provides a Model Context Protocol (MCP) server that bridges AI agents (Claude, Cursor, Antigravity, etc.) with your backend platform. Describe your API in plain English, and the agent automatically generates the schema, CRUD endpoints, and access control.

Prerequisites

1. Generate Agent API Keys from the Dashboard → Agent API Keys
2. Have Node.js ≥ 18 installed on your machine

Quick Start Configuration

Add the following configuration to your AI IDE setting. Replace agent-xxxxxxxxxxxx and your-client-secret with your Agent API Key credentials.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "igniral": {
      "command": "npx",
      "args": ["-y", "igniral-mcp-server"],
      "env": {
        "IGNIRAL_CLIENT_ID": "agent-xxxxxxxxxxxx",
        "IGNIRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "igniral": {
      "command": "npx",
      "args": ["-y", "igniral-mcp-server"],
      "env": {
        "IGNIRAL_CLIENT_ID": "agent-xxxxxxxxxxxx",
        "IGNIRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Antigravity (~/.gemini/antigravity/mcp_config.json)

{
  "mcpServers": {
    "igniral": {
      "command": "npx",
      "args": ["-y", "igniral-mcp-server"],
      "env": {
        "IGNIRAL_CLIENT_ID": "agent-xxxxxxxxxxxx",
        "IGNIRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Note: Antigravity may not inherit your shell's PATH. Use the absolute path to npx or node (e.g., /opt/homebrew/bin/npx) if you get "executable not found" errors.

Available Agent Tools

• igniral_generate_schema_from_prompt: Auto-generate a complete app from a natural language description.
• igniral_create_application: Create an empty application shell.
• igniral_create_dynamic_endpoint: Add API endpoints to an existing application.
• igniral_list_applications: List your existing applications.

Frequently Asked Questions