Authentication

What it does

Dreambase POSTs webhook events to the Authentication service; the service acts on them — verifying credentials, running health checks, executing function calls — and calls back into the Dreambase API to report status, logs, and outputs such as the publishable and secret keys other services consume.

Integrations

Each integration has its own dedicated reference page:

Each integration is its own webhook route:

The clerk route attaches to an existing (shared or dedicated) Clerk application, while clerk-server provisions a brand-new one — the same relationship as postgres vs. postgres-server in the Database service. The generic auth route is a deployment-less placeholder for an external or unmanaged identity provider, analogous to the generic database service.

Clerk

Clerk provides authentication and user management. Like the database integrations, the Clerk service offers two server types:

• Shared — use a Dreambase-managed Clerk application. No setup required; ideal for MVPs and development.
• Dedicated — connect to your own Clerk application by supplying its publishable key (pk_…) and secret key (sk_…).

On DEPLOYMENT_CREATED the service verifies the keys against the Clerk Backend API and exposes publishableKey, secretKey, and frontendApiUrl as outputs for other services to wire into.

Clerk Server (provisioned applications)

The clerk-server integration goes a step further and creates a dedicated Clerk application for you, programmatically. On DEPLOYMENT_CREATED it calls Clerk's Platform API (POST /platform/applications) to create a new application and instance, then publishes applicationId, instanceId, publishableKey, secretKey, and frontendApiUrlas outputs — the create response returns each instance's keys. On DEPLOYMENT_DELETED it calls DELETE /platform/applications/{id}, resolving the application id from the deployment outputs so teardown works even after a cold start.

The Platform API is authenticated with a Platform API access token (distinct from a Backend secret key), supplied per deployment (platformApiKey) or via the CLERK_PLATFORM_API_KEY environment variable. The environmentType input chooses which instance to create: development (default — no domain needed, test keys) or production (requires a domain, live keys). Health checks, metrics, downloads, and the functions below then run against the provisioned instance via the Backend API.

Functions it exposes

Other services can call these via a FUNCTION_CALL event:

• createUser, getUser, listUsers, updateUser, deleteUser, countUsers — manage users.
• createOrganization, listOrganizations — manage organizations.

A function call arrives as an event shaped like this:

POST /clerk/webhook
{
  "name": "FUNCTION_CALL",
  "functionCall": {
    "name": "createUser",
    "arguments": {
      "emailAddress": "user@example.com",
      "firstName": "Ada",
      "lastName": "Lovelace"
    }
  }
}

Events it handles

• WEBHOOK_CHALLENGE — verify the webhook endpoint.
• HEALTH_CHECK — confirm the Clerk Backend API is reachable.
• METRIC_UPDATE — report number_of_users and number_of_organizations.
• DEPLOYMENT_CREATED — verify credentials and return the keys as outputs.
• DEPLOYMENT_DELETED — stop the deployment.
• DOWNLOAD_STARTED — generate a .env.local file or a Next.js middleware.ts snippet.
• FUNCTION_CALL — run a named user/organization function.

Configuration

The service is configured through environment variables. The most important ones: