Self-Serve Signup

Atlas includes a self-serve signup flow that walks new users through account creation, workspace setup, and database connection — all from the browser. Once complete, users land in the chat UI ready to query.

How It Works

The signup wizard is a five-step flow at /signup:

Each step validates before allowing the user to proceed. The database URL is tested against the live server before being saved.

Region Selection

In step 3, new users choose a data region for their workspace. This determines where all workspace data (conversations, audit logs, cached results) is physically stored.

Available Regions

Atlas supports three regions at launch:

The platform's default region is pre-selected. Users can choose a different region based on their compliance requirements.

Why It Matters

• Data residency — All workspace data stays in the selected region. This is critical for organizations subject to GDPR, CCPA, or other data sovereignty regulations
• Latency — Choosing a region close to your users and database reduces round-trip time
• Permanence — Region assignment is permanent at signup. To change regions later, workspace admins can request a migration from the Data Residency page in the admin console

How It Works

1. The page loads available regions from GET /api/v1/onboarding/regions
2. If residency is not configured (configured: false), the step is skipped and the user proceeds directly to database connection
3. The user selects a region and clicks Continue
4. The selection is saved via POST /api/v1/onboarding/assign-region
5. The user proceeds to the database connection step

Enabling Social Login

Social OAuth buttons appear automatically when the corresponding environment variables are set. Each provider requires both a client ID and client secret:

# .env — enable Google and GitHub OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

The signup page checks which providers are available via GET /api/v1/onboarding/social-providers and renders OAuth buttons accordingly. If no social providers are configured, only email/password signup is shown.

See Social Providers for detailed OAuth setup instructions per provider.

Database Connection

In step 4, the user pastes a database URL (postgresql:// or mysql://). The wizard:

1. Validates the URL scheme — only PostgreSQL and MySQL are supported
2. Tests connectivity — creates a temporary connection, runs a health check, reports latency
3. Persists on success — encrypts the URL at rest and saves it scoped to the user's workspace

The connection is registered with a default ID of "default". If you need multiple datasources, add them later via the Admin Console.

Connection ID Rules

Custom connection IDs (optional) must be:

• 2–64 characters
• Lowercase alphanumeric, hyphens, or underscores
• Must start with a lowercase letter (a-z)
• Must end with a lowercase letter or digit

API Endpoints

The onboarding API is mounted at /api/v1/onboarding. All endpoints require managed auth mode.

Test Connection

curl -X POST https://your-atlas.example.com/api/v1/onboarding/test-connection \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{ "url": "postgresql://user:pass@host:5432/mydb" }'

Response:

{
  "status": "healthy",
  "latencyMs": 42,
  "dbType": "postgresql",
  "maskedUrl": "postgresql://user:****@host:5432/mydb"
}

Complete Onboarding

curl -X POST https://your-atlas.example.com/api/v1/onboarding/complete \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{ "url": "postgresql://user:pass@host:5432/mydb" }'

Response (201):

{
  "connectionId": "default",
  "dbType": "postgresql",
  "maskedUrl": "postgresql://user:****@host:5432/mydb"
}

Configuration (Self-Hosted)

// atlas.config.ts
export default defineConfig({
  auth: "managed",
  datasources: {
    default: { url: process.env.ATLAS_DATASOURCE_URL! },
  },
});

For most self-serve deployments, the datasource URL comes from the onboarding flow rather than a static config file. The atlas.config.ts is primarily used for self-hosted deployments with pre-configured connections.

After Signup

Once a user completes onboarding:

1. Their workspace is active with one datasource connection
2. The semantic layer whitelist cache is flushed, so new tables are queryable immediately
3. They can start chatting, or run atlas init to generate a semantic layer from the connected database

For semantic layer setup, see Semantic Layer.

See Also

• Authentication — Auth mode setup and configuration
• Social Providers — Detailed OAuth setup per provider
• Admin Console — Manage connections and users after signup
• Data Residency — Manage region assignment and migration after signup
• Environment Variables — Full variable reference