Documentation

basefyio is a self-hosted backend-as-a-service platform that gives every project its own dedicated database, NoSQL document data engine, authentication system, file storage, and auto-generated REST API. Deploy with Docker Compose, manage via the Admin Dashboard, and build applications with the SDK or CLI.

Quick Start

Create a free account at app.basefyio.com, create a project, and start building.

1. Install the SDK

npm install basefyio-js

2. Initialize the Client

import { createClient } from 'basefyio-js'

const bf = createClient({
  apiUrl: 'https://api.basefyio.com',
  projectId: 'your-project-id',
  apiKey: 'your-anon-key',
})

3. Start Building

// Query relational data (database)
const { data: posts } = await bf.from('posts').select().eq('published', true)

// Insert a document (Data Engine)
const { data: patient } = await bf.data.collection('patients').insert({
  firstName: 'John',
  address: { city: 'Istanbul', country: 'TR' },
})

// Query documents with nested filters
const { data: results } = await bf.data.collection('patients')
  .find({ 'address.city': 'Istanbul' })
  .sort('_createdAt', 'desc')
  .limit(20)

// Sign up a user
const { data: user } = await bf.auth.signUp({
  email: 'user@example.com',
  password: 'securepassword',
})

// Upload a file
await bf.storage.from('avatars').upload('user-123.jpg', file)

// Get a signed URL
const { data: url } = await bf.storage.from('avatars').createSignedUrl('user-123.jpg', 3600)

Explore

Platform Overview

Every basefyio project is a complete backend, isolated from other projects. When you create a project, you get:

Core Concepts

Projects & Teams

Projects are the fundamental unit of isolation. Each project belongs to a team, and team members have role-based access: OWNER, ADMIN, or MEMBER. Each role has granular permissions for project management, member management, billing, and integrations. A personal team is created automatically for every user.

Two Data Planes

basefyio gives you two ways to store data, both accessible from the same SDK:

• database (relational) — Full SQL power. Use bf.from('table') for structured data with relations, constraints, RLS policies, and joins. Best for: users, orders, products, anything with strong schemas and relationships.
• Data Engine (documents) — Schema-driven NoSQL. Use bf.data.collection('entity') for flexible documents with nested objects, arrays, versioning, and soft-delete. Best for: CMS content, form submissions, AI-generated data, mobile app records, IoT events.

Both planes are available simultaneously. database handles system metadata and relational data; the Data Engine handles application records and document workloads. See the Data Engine guide for details.

API Keys

Every project has two API keys:

• Anon key — Safe for client-side code. Provides access to public endpoints and respects Row-Level Security policies. Include it in the apikey header.
• Service key — Private, full access. Bypasses RLS. Use only server-side, never expose in client code or public repositories.

Authentication

Each project has its own auth realm with independent users, sessions, and OAuth providers. Supported authentication methods:

• Email/password — Sign up, sign in, email verification with OTP, password reset
• Magic links — Passwordless email-based authentication
• OAuth — Google and GitHub (configurable per project from the dashboard)
• JWT tokens — Access tokens (short-lived) + refresh tokens (long-lived). The SDK handles refresh automatically.

Configure providers, token lifetimes, email templates, and password policies from the project's Auth tab in the dashboard.

Storage

S3-compatible file storage powered by object storage. Each project can have multiple storage buckets:

• Private buckets — Files accessible only via signed URLs (time-limited) or the service key
• Public buckets — Files accessible via permanent public URLs
• Upload files up to 10 MB via the API, larger files via direct object storage access
• Organize files into folders within buckets

Row-Level Security (RLS)

Every project database comes with RLS roles pre-installed: anon, authenticated, and service_role. Write database RLS policies to control which rows each role can see, insert, update, or delete. The API automatically switches to the correct role based on the JWT token. See the Security & RLS guide.

SQL Editor

Execute arbitrary SQL queries against your project database from the dashboard. Features: syntax highlighting, query history, execution time tracking, result export, and full audit logging of every query.

Table Editor

Visual spreadsheet-style editor for your database tables. Create tables, add/edit/delete columns, insert rows, inline-edit cells, manage foreign keys, sort, filter, paginate, and deduplicate — all without writing SQL.

Real-time Events

basefyio streams project activity events via Server-Sent Events (SSE). Subscribe to channels for real-time updates on data changes, schema modifications, auth events, and more. The Admin Dashboard uses real-time events to show live activity feeds and toast notifications.

Integrations

Connect your project to external services:

• GitHub — Link a repository for schema versioning and CI/CD
• Vercel — Auto-deploy frontend applications

Billing & Plans

Team-level subscriptions managed via Stripe. Plans define limits for: projects, storage, database size, team members, API requests, bandwidth, and monthly active users. Usage is tracked in real-time and visible from the dashboard.

Architecture

┌──────────────────────────────────────────┐
│   Client (Browser / Mobile / Server)     │
│   SDK (basefyio-js) or direct REST       │
└──────────────┬───────────────────────────┘
               │ HTTPS
┌──────────────▼───────────────────────────┐
│   Platform API (NestJS)                  │
│   ├── REST API (/rest/v1)                │
│   ├── Data Engine (/v1/projects/:id/data)│
│   ├── Auth (/rest/v1/auth)               │
│   ├── Storage (/storage)                 │
│   ├── SQL (/sql/execute)                 │
│   └── Admin (/projects, /teams, ...)     │
└──────┬──────────┬──────────┬─────────────┘
       │          │          │
  ┌────▼────┐ ┌──▼───┐ ┌───▼────┐
  │database│ │NoSQL │ │auth service│
  │  16      │ │Store │ │  24    │
  └─────────┘ └──────┘ └────────┘
       │                    │
  ┌────▼────┐          ┌───▼────┐
  │PgBouncer│          │ object storage  │
  └─────────┘          └────────┘

Admin Dashboard

The Admin Dashboard at app.basefyio.com is your visual management interface. Each project has these sections:

What's Next

• Data Engine guide — Learn about the NoSQL document data plane
• API Reference — Complete REST API documentation
• SDK Reference — JavaScript/TypeScript client library
• CLI Reference — Command-line project management
• Security & RLS — Row-level security and access control
• Self-Hosting — Deploy basefyio with Docker Compose