# Popup Studio AI Bkit Gemini Bkend Quickstart > bkend-quickstart - Skill: `tomevault-io/popup-studio-ai-bkit-gemini-bkend-quickstart` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/popup-studio-ai-bkit-gemini-bkend-quickstart` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/popup-studio-ai-bkit-gemini-bkend-quickstart/raw - Safety review: pending (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/popup-studio-ai-bkit-gemini-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: X-Environment: ``` **Authentication Headers (choose one):** ```http # For tenant/server-side calls X-API-Key: # For user-authenticated calls Authorization: Bearer ``` **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: { "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: { "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( path: string, options: BkendFetchOptions = {} ): Promise { const { token, headers: customHeaders, ...rest } = options; const headers: Record = { "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, }; // 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`): ```dart import 'package:dio/dio.dart'; class BkendClient { late final Dio _dio; BkendClient({ required String projectId, required String environment, String? apiKey, }) { _dio = Dio(BaseOptions( baseUrl: 'https://api-client.bkend.ai', headers: { 'Content-Type': 'application/json', 'X-Project-Id': projectId, 'X-Environment': environment, if (apiKey != null) 'X-API-Key': apiKey, }, )); _dio.interceptors.add(AuthInterceptor()); } Future> get(String path, { Map? queryParameters, }) => _dio.get(path, queryParameters: queryParameters); Future> post(String path, {dynamic data}) => _dio.post(path, data: data); Future> put(String path, {dynamic data}) => _dio.put(path, data: data); Future> delete(String path) => _dio.delete(path); } ``` **Auth Interceptor** (`lib/core/network/auth_interceptor.dart`): ```dart import 'package:dio/dio.dart'; import 'package:flutter_secure_storage/flutter_secure_storage.dart'; class AuthInterceptor extends Interceptor { final _storage = const FlutterSecureStorage(); @override void onRequest(RequestOptions options, RequestInterceptorHandler handler) async { final token = await _storage.read(key: 'access_token'); if (token != null) { options.headers['Authorization'] = 'Bearer $token'; } handler.next(options); } @override void onError(DioException err, ErrorInterceptorHandler handler) async { if (err.response?.statusCode == 401) { final refreshToken = await _storage.read(key: 'refresh_token'); if (refreshToken != null) { try { final dio = Dio(); final res = await dio.post( 'https://api-client.bkend.ai/auth/token/refresh', data: {'refreshToken': refreshToken}, options: Options(headers: err.requestOptions.headers), ); final newToken = res.data['data']['accessToken']; await _storage.write(key: 'access_token', value: newToken); // Retry original request err.requestOptions.headers['Authorization'] = 'Bearer $newToken'; final retryRes = await dio.fetch(err.requestOptions); handler.resolve(retryRes); return; } catch (_) { await _storage.deleteAll(); } } } handler.next(err); } } ``` ## 6. Console Guide Summary The bkend.ai Console (`https://console.bkend.ai`) provides visual management for all platform features: | Section | Description | |---------|-------------| | **Projects** | Create, configure, and manage projects | | **Environments** | Switch between dev/staging/prod environments | | **Tables** | Create collections, define schemas, browse data | | **API Keys** | Generate and revoke API keys per environment | | **Auth** | View registered users, manage sessions | | **Storage** | Browse uploaded files, manage buckets | | **Team** | Invite members, assign roles (Owner/Admin/Member) | | **Settings** | Project configuration, custom domains, webhooks | | **Logs** | View API request logs and error traces | ## 7. Environment Variables Reference | Variable | Required | Description | Example | |----------|----------|-------------|---------| | `NEXT_PUBLIC_BKEND_API_URL` | Yes | bkend API base URL | `https://api-client.bkend.ai` | | `NEXT_PUBLIC_BKEND_PROJECT_ID` | Yes | Your project ID | `proj_abc123` | | `NEXT_PUBLIC_BKEND_ENVIRONMENT` | Yes | Target environment | `dev` | | `BKEND_API_KEY` | Server only | API key for server-side calls | `bk_key_...` | | `NEXT_PUBLIC_BKEND_MCP_URL` | Optional | MCP server URL | `https://api.bkend.ai/mcp` | | `BKEND_WEBHOOK_SECRET` | Optional | Webhook signature secret | `whsec_...` | | `NEXT_PUBLIC_GOOGLE_CLIENT_ID` | Optional | Google OAuth client ID | `123...apps.googleusercontent.com` | | `NEXT_PUBLIC_GITHUB_CLIENT_ID` | Optional | GitHub OAuth client ID | `gh_abc123` | ## 8. Next Steps Once you have completed setup, use the following bkend-* skills for each domain: | Domain | Skill | Description | |--------|-------|-------------| | Authentication | `/bkend-auth` | Email/social login, JWT, sessions, RBAC, MFA | | Data Operations | `/bkend-data` | CRUD, queries, filtering, pagination, relations | | File Storage | `/bkend-storage` | Upload, download, presigned URLs, image transforms | | Security | `/bkend-security` | RLS policies, rate limiting, CORS, audit logs | | MCP Tools | `/bkend-mcp` | MCP server tools reference and advanced usage | | Realtime | `/bkend-realtime` | WebSocket subscriptions, live queries | | Functions | `/bkend-functions` | Server-side functions, webhooks, scheduled tasks | ### Recommended Learning Path 1. **Start here** (bkend-quickstart) -- you are here 2. **Authentication** (`/bkend-auth`) -- set up user auth for your app 3. **Data Operations** (`/bkend-data`) -- CRUD and query patterns 4. **Storage** (`/bkend-storage`) -- file uploads and management 5. **Security** (`/bkend-security`) -- production-ready security policies --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/popup-studio-ai) — claim your Tome and manage your conversions.