app-services

name	app-services
summary	Couchbase Capella App Services — managed Sync Gateway for mobile and edge sync, App Endpoint configuration, access control, user management, and the App Services Management API
description	Couchbase Capella App Services — managed Sync Gateway for mobile and edge sync, App Endpoint configuration, access control, user management, and the App Services Management API
compatibility	Couchbase Capella. Requires a Capella Operational cluster (free tier not supported for App Services).
metadata	{"last_verified":"2026-05","handoff":[{"condition":"user asks about sync or replication setup","type":"variant","skill":"mobile-sync-android"},{"condition":"user asks about document design or channel strategy","skill":"mobile-data-modeling"},{"condition":"user asks about Capella cluster setup or credentials","skill":"capella"}]}

Couchbase Capella App Services

App Services is the managed Sync Gateway service on Capella. It provides bi-directional sync between Couchbase Lite (mobile/edge) and Capella clusters without running or maintaining Sync Gateway infrastructure.

Template: templates/sync-function.js — copy this skeleton as a starting point for new Sync Functions.

Key differences from self-hosted Sync Gateway

Area	App Services	Self-hosted Sync Gateway
Setup	Managed — provisioned via Capella UI or API	Manual install, config file, OS management
Admin API	App Services Management API (https://cloud.couchbase.com/...)	REST on port 4985
TLS	Always on — wss:// only	Configurable
Delta sync	Enabled by default	Requires config
Import filter	Not supported	Supported
Metrics	Capella UI + Management API	Prometheus endpoint on port 4986
Sync Function	Supported (JavaScript)	Supported (JavaScript)
Access grants	App Services users + roles	Sync Gateway users + roles

Provisioning an App Endpoint

An App Endpoint is the App Services equivalent of a Sync Gateway database. Each App Endpoint maps to one Couchbase bucket and exposes a sync URL.

Via Capella UI

1. Capella → your cluster → App Services tab
2. Create App Service → name it, select the cluster
3. Once created: Create App Endpoint → select bucket, name the endpoint
4. Configure the Sync Function under App Endpoint → Config

Via Management API

# Create an App Endpoint
curl -X POST \
  "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORG_ID/projects/$PROJECT_ID/clusters/$CLUSTER_ID/appservices/$APP_SERVICE_ID/endpoints" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myapp",
    "bucket": "myapp",
    "syncFunction": "function sync(doc, oldDoc) { channel(doc.userId); requireUser(doc.userId); }"
  }'

Sync Function

The Sync Function is JavaScript that runs on every document write. It controls:

• Which channels a document belongs to
• Which users can read/write the document

function sync(doc, oldDoc) {
    // Validate required fields
    if (!doc.userId) throw({ forbidden: "userId is required" });

    // Route to user's private channel
    channel("user." + doc.userId);

    // Require the writing user to own the document
    requireUser(doc.userId);

    // Admin role can write anything
    if (isAdmin()) return;

    // Prevent changing ownership
    if (oldDoc && oldDoc.userId !== doc.userId) {
        throw({ forbidden: "cannot change document owner" });
    }
}

Deploy via Capella UI (App Endpoint → Config → Sync Function) or API:

curl -X PUT \
  "https://cloudapi.cloud.couchbase.com/v4/.../endpoints/myapp/syncFunction" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"syncFunction": "function sync(doc, oldDoc) { channel(doc.userId); requireUser(doc.userId); }"}'

App Services users

App Services users are separate from Capella database credentials and Couchbase Server RBAC users.

Create a user via Management API

curl -X POST \
  "https://cloudapi.cloud.couchbase.com/v4/.../endpoints/myapp/users" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "alice",
    "password": "$SG_USER_PASSWORD",
    "admin_channels": [],
    "admin_roles": []
  }'

Grant channel access

# Grant alice access to her private channel
curl -X PUT \
  "https://cloudapi.cloud.couchbase.com/v4/.../endpoints/myapp/users/alice" \
  -H "Authorization: Bearer $CAPELLA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"admin_channels": ["user.alice"]}'

Connecting Couchbase Lite to App Services

The connection string format is the App Endpoint's public URL:

wss://<app-service-host>/<endpoint-name>

Find it in Capella UI: App Services → your App Service → App Endpoint → Connection.

For platform-specific replication setup (ReplicatorConfiguration, authenticators, filters), see mobile-sync-android (Kotlin) or mobile-sync-ios (Swift). The only difference from self-hosted Sync Gateway is the wss:// URL — use the App Endpoint URL above instead of a self-hosted Sync Gateway URL.

Access control patterns

Pattern	Sync Function	Use case
Private per-user	channel("user." + doc.userId); requireUser(doc.userId)	Personal data
Shared team	channel("team." + doc.teamId); requireAccess("team." + doc.teamId)	Collaboration
Public read	channel("public"); requireRole("writer") for writes	Read-heavy content
Admin override	if (isAdmin()) return; before requireUser	Support access

Troubleshooting

Symptom	Cause	Fix
401 on replication	Wrong App Services credentials	Use App Services user, not Capella login
403 on document write	Sync Function rejected write	Check requireUser/requireRole logic
Documents not syncing	Channel mismatch	Verify Sync Function assigns correct channels
App Endpoint not reachable	IP not allowlisted	Add IP in Capella → App Services → Allowed IPs
wss:// connection refused	Wrong endpoint URL	Copy URL from Capella UI → App Endpoint → Connection