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

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:

• 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:

X-Project-Id: <your-project-id>
X-Environment: <dev|staging|prod>

Authentication Headers (choose one):

# For tenant/server-side calls
X-API-Key: <your-api-key>

# For user-authenticated calls
Authorization: Bearer <access-token>

Standard Response Format:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Standard Error Format:

{
  "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

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

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:

X-Project-Id: proj_abc123
X-Environment: dev

Step 5: Create a Table

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:

POST https://api-client.bkend.ai/api-keys
X-Project-Id: proj_abc123
X-Environment: dev

Step 7: Call the API

# 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:

{
  "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:

{
  "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:

{
  "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):

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):

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):

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):

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<Response<T>> get<T>(String path, {
    Map<String, dynamic>? queryParameters,
  }) => _dio.get<T>(path, queryParameters: queryParameters);

  Future<Response<T>> post<T>(String path, {dynamic data}) =>
      _dio.post<T>(path, data: data);

  Future<Response<T>> put<T>(String path, {dynamic data}) =>
      _dio.put<T>(path, data: data);

  Future<Response<T>> delete<T>(String path) => _dio.delete<T>(path);
}

Auth Interceptor (lib/core/network/auth_interceptor.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:

7. Environment Variables Reference

8. Next Steps

Once you have completed setup, use the following bkend-* skills for each domain:

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