urBackend 🚀

Bring your own MongoDB. Get a production-ready backend in 60 seconds.
your backend — your database — your rules.

Dashboard · Docs · Quick Start · Discord

License: Core apps/packages are AGPL-3.0-only · examples and @urbackend/sdk are MIT.
Contributions currently do not require CLA/DCO; submitted changes are licensed under the package license they modify (details in CONTRIBUTING.md).

---

urBackend is an Open-Source BaaS built to eliminate the complexity of backend management. It provides everything you need to power your next big idea—accessible via a unified REST API.

🟢 Powerful Features

Feature	Description
Instant NoSQL	Create collections and push JSON data instantly with zero boilerplate.
Managed Auth	Sign Up, Login, and Profile management with JWT built-in.
Cloud Storage	Managed file/image uploads with public CDN links.
BYO Database	Connect your own MongoDB Atlas or self-hosted instance.
Real-time Analytics	Monitor traffic and resource usage from a premium dashboard.
Unique Constraints	Enforce field uniqueness (e.g., username, email) at the database level.
Secure Architecture	Dual-key separation (pk_live & sk_live) for total safety.

---

🚀 Quick Start

Go from zero to a live backend in under 60 seconds.

1. Initialize: Create a project on the Dashboard.
2. Install SDK:
   • Node.js / TS: npm install @urbackend/sdk
   • Python: pip install urbackend
3. Model: Visually define your collections and schemas.
4. Execute: Push and pull data immediately using the SDK.

TypeScript / Node.js

import urBackend from '@urbackend/sdk';

// Initialize with your API key
const client = urBackend({ apiKey: 'YOUR_API_KEY' });

// Read data (GET /api/data/products)
const products = await client.db.getAll('products');

// Write data (POST /api/data/products)
// requires sk_live_* key or RLS enabled
const product = await client.db.insert('products', { 
  name: 'Widget', 
  price: 9.99 
});

Python

from urbackend import UrBackendClient

# Initialize with your API key
client = UrBackendClient(api_key='YOUR_API_KEY')

# Read data (GET /api/data/products)
products = client.db.get_all('products')

# Write data (POST /api/data/products)
# requires sk_live_* key or RLS enabled
product = client.db.insert('products', {
    'name': 'Widget',
    'price': 9.99
})

---

🔑 Key Behavior: pk_live vs sk_live

Understanding which key to use—and when—prevents the most common integration mistakes.

Scenario	Key	Auth Token	Result
Read any collection	pk_live	Not required	✅ Allowed
Write to a collection (RLS disabled)	pk_live	Any	❌ 403 Blocked
Write to a collection (RLS disabled)	sk_live	Not required	✅ Allowed
Write to a collection (RLS enabled, no token)	pk_live	Missing	❌ 401 Unauthorized
Write to a collection (RLS enabled, wrong owner)	pk_live	Token with different userId	❌ 403 Owner mismatch
Write to a collection (RLS enabled, correct owner)	pk_live	Token with matching userId	✅ Allowed
Write to a collection (RLS enabled, no ownerField)	pk_live	Valid token	✅ Allowed (userId auto-injected)
Access /api/data/users*	Any	Any	❌ 403 Blocked — use /api/userAuth/*

Rule of thumb: pk_live is for frontend reads. Use sk_live for server-side writes, or enable collection RLS to allow authenticated users to write their own data with pk_live.

---

🛡️ Row-Level Security (RLS)

RLS lets you safely allow frontend clients to write data without exposing your secret key. When enabled on a collection, pk_live writes are gated by user ownership and reads can be scoped by mode.

How it works:

1. Enable RLS for a collection in the Dashboard and choose a mode.
2. Use public-read for content anyone can view, or private for owner-only access. (owner-write-only is treated as public-read for legacy projects.)
3. Choose the owner field — the document field that stores the authenticated user's ID (e.g., userId).
4. The client must send a valid user JWT in the Authorization: Bearer <token> header for pk_live writes and for private reads.
5. urBackend enforces that the JWT's userId matches the document's owner field.

Example — user creates a post:

// 1. User logs in (POST /api/userAuth/login)
const { accessToken } = await client.auth.login({ 
  email: 'user@example.com', 
  password: 'secret' 
});

// 2. User creates a post (POST /api/data/posts)
// accessToken is auto-handled by the SDK after login
const post = await client.db.insert('posts', { 
  title: 'Hello World', 
  content: '...' 
});
// The saved document will include: { userId: '<logged-in user id>', title: 'Hello World', ... }

Common failure cases:

Error	Cause	Fix
403 Write blocked for publishable key	RLS is not enabled on the collection	Enable RLS in Dashboard, or use sk_live
401 Authentication required	No Authorization header provided	Add Authorization: Bearer <user_jwt>
403 RLS owner mismatch	Token's userId ≠ document's owner field	Make sure the user is writing their own data
403 Insert denied (ownerField _id)	_id is not a valid owner field for inserts	Change ownerField to userId or similar
403 Owner field immutable	Trying to change the owner field on update	Remove the owner field from the PATCH/PUT body

Public Signup

By default, new users can sign up using email/password or social providers. You can disable public signups from the Authentication page in the dashboard under the Allow Public Signups toggle. When disabled, the API blocks new registrations, allowing only existing users to log in.

---

Social Auth

Social Auth is configured in a Supabase-style flow:

1. Set your project's Site URL in Project Settings.
2. Open Auth -> Social Auth in the dashboard.
3. Copy the read-only callback URL shown for GitHub or Google.
4. Register that callback URL in the provider console.
5. Paste the provider Client ID and Client Secret into urBackend and enable the provider.

After a successful provider login, urBackend redirects users back to: <Site URL>/auth/callback

The frontend callback flow is:

1. Read token from the URL fragment and rtCode from the query string.
2. Call POST /api/userAuth/social/exchange with JSON:
   • token
   • rtCode
3. Expect a standard response in the form { success, data, message }.
4. On success, store the original access token together with data.refreshToken.
5. Continue into the signed-in app.

Callback example:

// After redirect from provider (POST /api/userAuth/social/exchange)
const token = new URLSearchParams(window.location.hash.slice(1)).get('token');
const rtCode = new URLSearchParams(window.location.search).get('rtCode');

const { refreshToken } = await client.auth.socialExchange({ token, rtCode });
// Success shape: { refreshToken }

GitHub and Google both support:

• linking existing users by email when the provider returns a verified email matching an existing account
• creating new users automatically when no matching account exists
• issuing the same urBackend access and refresh tokens used by normal auth flows
• backend-generated read-only provider callback URLs in the dashboard
• redirecting to the project Site URL after provider login

---

👤 User Authentication

User accounts are managed through the SDK's auth module — not through the database API. Direct access to /api/data/users* is blocked for security.

// Sign up a new user (POST /api/userAuth/signup)
await client.auth.signUp({ 
  email: "user@example.com", 
  password: "secret", 
  name: "Alice" 
});

// Log in (POST /api/userAuth/login)
const { accessToken, user } = await client.auth.login({ 
  email: "user@example.com", 
  password: "secret" 
});

// Get current user profile (GET /api/userAuth/me)
// Uses the accessToken from the previous login automatically
const me = await client.auth.me();

All auth methods require your pk_live key. See the full auth docs for more.

---

🏗️ How it Works

graph LR
    A[1. Connect MongoDB] --> B[2. Define Collections]
    B --> C[3. 🚀 Instant REST APIs]
    C --> D[4. Scale & Monitor]

Loading

---

🏗️ Architecture

Explore our Architecture Diagram to understand the system design, core components, and data flow in detail.

---

🏠 Self-Hosting

Want to run your own instance? Follow the step-by-step guide to deploy urBackend to Render (backend) and Vercel (frontend) using free-tier services — no Docker required.

👉 DEPLOYMENT.md

---

🤝 Community

Join hundreds of developers building faster without the backend headaches.

• GitHub Issues: Report bugs & request features.
• Discord Channel: Join the conversation.
• Contributing: Help us grow the ecosystem.

---

---

Star History

---

Contributors

Built with ❤️ by the urBackend community. . .