bkend-quickstart

# bkend-quickstart > bkend.ai platform onboarding and core concepts guide ## 1. What is bkend.ai bkend.ai is a **Backend-as-a-Service (BaaS)** platform built on **MongoDB Atlas**. It provides: - **REST API** endpoints for CRUD operations, authentication, file storage, and more - **MCP (Model Context Protocol)** server for AI-assisted development with Gemini CLI, Claude Code, and Cursor - **Console UI** at `https://console.bkend.ai` for visual management - **Zero-config database** powered by MongoDB Atlas (no schema migration needed) - **Multi-tenant architecture** with project-level isolation ### Key Differentiators | Feature | bkend.ai | Traditional BaaS | |---------|----------|-------------------| | AI Integration | Native MCP support | None | | Database | MongoDB Atlas (managed) | Self-managed | | Schema | Schemaless / flexible | Rigid migrations | | Auth | Built-in JWT + Social | Plugin-based | | File Storage | Integrated | Separate service | ## 2. Core Concepts ### 2.1 Resource Hierarchy ``` Organization (Org) └── Project └── Environment (dev / staging / prod) ├── Tables (collections) ├── Auth (users, sessions) ├── Storage (files, buckets) └── API Keys ``` - **Organization**: Top-level billing and team boundary. One user can belong to multiple orgs. - **Project**: A single application or service. Contains its own database, auth, and storage. - **Environment**: Isolated runtime context within a project. Each environment has its own data, API keys, and configuration. Default environments: `dev`, `staging`, `prod`. ### 2.2 Tenant vs User Model bkend.ai distinguishes between two identity layers: | Concept | Tenant | User | |---------|--------|------| | Who | Developer / team member | End-user of your app | | Scope | Console + API management | App-level auth | | Auth | Console login | `/auth/*` endpoints | | Permissions | Org/Project roles | RBAC (admin/user/self/guest) | | API Key | Yes (X-API-Key) | No (uses JWT) | - **Tenant**: You, the developer. Manages projects via the Console or API keys. - **User**: Your application's end-user. Authenticates via email, social login, or magic link. ### 2.3 API Structure **Base URL:** ``` https://api-client.bkend.ai ``` **MCP URL:** ``` https://api.bkend.ai/mcp ``` **Required Headers for all API calls:** ```http X-Project-Id: <your-project-id> X-Environment: <dev|staging|prod> ``` **Authentication Headers (choose one):** ```http # For tenant/server-side calls X-API-Key: <your-api-key> # For user-authenticated calls Authorization: Bearer <access-token> ``` **Standard Response Format:** ```json { "success": true, "data": { ... }, "meta": { "page": 1, "limit": 20, "total": 100 } } ``` **Standard Error Format:** ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid email format", "details": [...] } } ``` ## 3. Quick Start Steps ### Step 1: Sign Up Visit `https://console.bkend.ai/signup` and create your tenant account. ### Step 2: Create an Organization ```http POST https://api-client.bkend.ai/orgs Content-Type: application/json { "name": "My Company", "slug": "my-company" } ``` Or use the Console: **Dashboard > Create Organization**. ### Step 3: Create a Project ```http POST https://api-client.bkend.ai/projects Content-Type: application/json X-Org-Id: <your-org-id> { "name": "My App", "slug": "my-app" } ``` Or use the Console: **Organization > New Project**. ### Step 4: Set Environment Each project starts with three environments: `dev`, `staging`, `prod`. Choose your target: ```http X-Project-Id: proj_abc123 X-Environment: dev ``` ### Step 5: Create a Table ```http POST https://api-client.bkend.ai/tables Content-Type: application/json X-Project-Id: proj_abc123 X-Environment: dev X-API-Key: <your-api-key> { "name": "todos", "schema": { "title": { "type": "string", "required": true }, "completed": { "type": "boolean", "default": false }, "priority": { "type": "number", "default": 0 } } } ``` ### Step 6: Get an API Key Navigate to **Console > Project > Settings > API Keys** and generate a new key. Or via API: ```http POST https://api-client.bkend.ai/api-keys X-Project-Id: proj_abc123 X-Environment: dev ``` ### Step 7: Call the API ```bash # Create a record curl -X POST https://api-client.bkend.ai/data/todos \ -H "Content-Type: application/json" \ -H "X-Project-Id: proj_abc123" \ -H "X-Environment: dev" \ -H "X-API-Key: your-api-key" \ -d '{"title": "Learn bkend", "completed": false}' # List records curl https://api-client.bkend.ai/data/todos \ -H "X-Project-Id: proj_abc123" \ -H "X-Environment: dev" \ -H "X-API-Key: your-api-key" ``` ## 4. MCP Setup ### 4.1 Gemini CLI Create or edit `~/.gemini/settings.json`: ```json { "mcpServers": { "bkend": { "httpUrl": "https://api.bkend.ai/mcp", "headers": { "X-Project-Id": "proj_abc123", "X-Environment": "dev", "X-API-Key": "your-api-key" } } } } ``` After setup, restart Gemini CLI. You can then use natural language: ``` > Create a users table with name, email, and age fields > Add a new user named Alice with email alice@example.com > List all users where age > 25 ``` ### 4.2 Claude Code Create or edit `.mcp.json` in your project root: ```json { "mcpServers": { "bkend": { "type": "http", "url": "https://api.bkend.ai/mcp", "headers": { "X-Project-Id": "proj_abc123", "X-Environment": "dev", "X-API-Key": "your-api-key" } } } } ``` ### 4.3 Cursor Open **Cursor Settings > MCP Servers** and add: ```json { "bkend": { "type": "http", "url": "https://api.bkend.ai/mcp", "headers": { "X-Project-Id": "proj_abc123", "X-Environment": "dev", "X-API-Key": "your-api-key" } } } ``` ## 5. Framework Quick Start ### 5.1 Next.js Setup **Environment Variables** (`.env.local`): ```env NEXT_PUBLIC_BKEND_API_URL=https://api-client.bkend.ai NEXT_PUBLIC_BKEND_PROJECT_ID=proj_abc123 NEXT_PUBLIC_BKEND_ENVIRONMENT=dev BKEND_API_KEY=your-api-key ``` **bkendFetch Client** (`lib/bkend.ts`): ```typescript interface BkendFetchOptions extends RequestInit { token?: string; } export async function bkendFetch<T = any>( path: string, options: BkendFetchOptions = {} ): Promise<T> { const { token, headers: customHeaders, ...rest } = options; const headers: Record<string, string> = { "Content-Type": "application/json", "X-Project-Id": process.env.NEXT_PUBLIC_BKEND_PROJECT_ID!, "X-Environment": process.env.NEXT_PUBLIC_BKEND_ENVIRONMENT!, ...customHeaders as Record<string, string>, }; // Server-side: use API key if (typeof window === "undefined" && process.env.BKEND_API_KEY) { headers["X-API-Key"] = process.env.BKEND_API_KEY; } // Client-side: use JWT token if (token) { headers["Authorization"] = `Bearer ${token}`; } const res = await fetch( `${process.env.NEXT_PUBLIC_BKEND_API_URL}${path}`, { headers, ...rest } ); if (!res.ok) { const error = await res.json(); throw new Error(error.error?.message || "bkend API error"); } return res.json(); } ``` **Middleware** (`middleware.ts`): ```typescript import { NextRequest, NextResponse } from "next/server"; export async function middleware(request: NextRequest) { const accessToken = request.cookies.get("bkend_access_token")?.value; const refreshToken = request.cookies.get("bkend_refresh_token")?.value; // Public routes - skip auth const publicPaths = ["/login", "/signup", "/"]; if (publicPaths.includes(request.nextUrl.pathname)) { return NextResponse.next(); } if (!accessToken && !refreshToken) { return NextResponse.redirect(new URL("/login", request.url)); } // Auto-refresh if access token is missing but refresh token exists if (!accessToken && refreshToken) { try { const res = await fetch( `${process.env.NEXT_PUBLIC_BKEND_API_URL}/auth/token/refresh`, { method: "POST", headers: { "Content-Type": "application/json", "X-Project-Id": process.env.NEXT_PUBLIC_BKEND_PROJECT_ID!, "X-Environment": process.env.NEXT_PUBLIC_BKEND_ENVIRONMENT!, }, body: JSON.stringify({ refreshToken }), } ); if (res.ok) { const data = await res.json(); const response = NextResponse.next(); response.cookies.set("bkend_access_token", data.data.accessToken, { httpOnly: true, secure: true, sameSite: "lax", maxAge: 3600, }); return response; } } catch { return NextResponse.redirect(new URL("/login", request.url)); } } return NextResponse.next(); } export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"], }; ``` ### 5.2 Flutter Setup **DioClient** (`lib/core/network/bkend_client.dart`):