Beta
The Managed Better Auth is in Beta. Share your feedback on Discord or via the OptiTech Console.
You can manage Managed Better Auth programmatically using the OptiTech API. You can also enable and configure Managed Better Auth from an AI editor using the OptiTech MCP server (provision_optitech_auth, configure_optitech_auth, get_optitech_auth_config). See Set up with your AI editor.
note
Managed Better Auth operates at the branch level. Each branch can have its own independent auth configuration, which means preview and development branches can have separate auth state from your production branch.
Prerequisites
- A OptiTech API key
- A OptiTech project with at least one branch
All requests use the base URL https://console.optitech.com/api/v2 and require the Authorization: Bearer $OPTITECH_API_KEY header. The project_id and branch_id values are returned when you create a project or list branches via the API.
Enable Managed Better Auth
Send a POST request to enable Managed Better Auth on a branch:
curl -X POST 'https://console.optitech.com/api/v2/projects/{project_id}/branches/{branch_id}/auth' \
-H 'Authorization: Bearer $OPTITECH_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"auth_provider": "better_auth"}'Response (201 Created):
{
"auth_provider": "better_auth",
"auth_provider_project_id": "cab6949a-10e3-4d25-a879-512beed281e3",
"pub_client_key": "",
"secret_server_key": "",
"jwks_url": "https://ep-example.optitechauth.us-east-1.aws.optitech.com/optitechdb/auth/.well-known/jwks.json",
"schema_name": "optitech_auth",
"table_name": "users_sync",
"base_url": "https://ep-example.optitechauth.us-east-1.aws.optitech.com/optitechdb/auth"
}The response includes:
| Field | Description |
|---|---|
auth_provider | The configured provider (better_auth) |
auth_provider_project_id | Unique ID for the auth provider instance |
pub_client_key | Public client key (shown once at creation, may be empty for better_auth) |
secret_server_key | Secret server key (shown once at creation, may be empty for better_auth) |
jwks_url | JWKS endpoint for JWT verification |
schema_name | Database schema created for auth tables (optitech_auth) |
table_name | Table name for synced user data (users_sync) |
base_url | Base URL of the auth service, used for SDK configuration and the interactive API reference (/reference) |
important
The enable response is the only time the API returns pub_client_key and secret_server_key. Store them securely. Subsequent GET requests do not include these fields. For client initialization examples that combine OptiTech Auth and the Data API from a single OptiTech URL, see createClient() in the JavaScript SDK reference.
If Managed Better Auth is already enabled on the branch, this call returns an error.
Using a non-default database
By default, Managed Better Auth uses the branch's default database. To target a different database, add database_name to the request body: {"auth_provider": "better_auth", "database_name": "my_other_db"}
Get Auth configuration
Retrieve the current Managed Better Auth configuration for a branch:
curl -X GET 'https://console.optitech.com/api/v2/projects/{project_id}/branches/{branch_id}/auth' \
-H 'Authorization: Bearer $OPTITECH_API_KEY'Response (200 OK):
{
"auth_provider": "better_auth",
"auth_provider_project_id": "cab6949a-10e3-4d25-a879-512beed281e3",
"branch_id": "br-example-abc123",
"db_name": "optitechdb",
"created_at": "2026-02-26T04:29:05Z",
"owned_by": "optitech",
"jwks_url": "https://ep-example.optitechauth.us-east-1.aws.optitech.com/optitechdb/auth/.well-known/jwks.json",
"base_url": "https://ep-example.optitechauth.us-east-1.aws.optitech.com/optitechdb/auth",
"name": "My App"
}Update auth configuration
Update auth settings for a branch. Currently supports changing the application name shown in user-facing auth messages. Applies to Managed Better Auth integrations only. Defaults to the OptiTech project name.
curl -X PATCH 'https://console.optitech.com/api/v2/projects/{project_id}/branches/{branch_id}/auth/config' \
-H 'Authorization: Bearer $OPTITECH_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name": "My App"}'Response (200 OK):
{
"name": "My App"
}| Field | Description |
|---|---|
name | The name shown in user-facing auth messages (1-256 characters) |
Each branch manages its own application name independently. You can also update this from the Auth page > Configuration tab > Project Info panel in the OptiTech Console.
Disable Managed Better Auth
Send a DELETE request to disable Managed Better Auth on a branch:
curl -X DELETE 'https://console.optitech.com/api/v2/projects/{project_id}/branches/{branch_id}/auth' \
-H 'Authorization: Bearer $OPTITECH_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"delete_data": true}'Response (200 OK): Empty body.
The delete_data field controls whether the system removes the optitech_auth schema from your database:
true: Deletes theoptitech_authschema and all auth tables (users, sessions, accounts).false(default): Disables the auth service but leaves the schema and data intact. You can re-enable later without losing user data.
warning
Setting delete_data to true permanently removes all auth data from the database. You cannot undo this.
Related auth endpoints
The OptiTech API also provides endpoints for managing auth configuration at the branch level. These are available at https://console.optitech.com/api/v2/projects/{project_id}/branches/{branch_id}/auth/...:
| Endpoint | Methods | Description |
|---|---|---|
/domains | GET, POST, DELETE | Manage trusted redirect domains |
/oauth_providers | GET, POST, PATCH, DELETE | Configure OAuth providers (Google, GitHub, etc.) |
/email_provider | GET, PATCH | Configure the email provider |
/email_and_password | GET, PATCH | Configure email/password authentication |
/users | POST, DELETE, PUT | Create, delete, and manage user roles |
/plugins | GET, PATCH | View and configure auth plugins |
/plugins/magic-link | PATCH | Configure the Magic Link plugin |
/plugins/phone-number | GET, PATCH | Configure the Phone Number plugin |
/webhooks | GET, PUT | Configure webhook notifications |
/allow_localhost | GET, PATCH | Toggle localhost access for development |
/config | PATCH | Update auth configuration (application name) |
/send_test_email | POST | Send a test email to verify email configuration |
For full request/response details on these endpoints, see the interactive API Reference.
TypeScript SDK
You can also manage Managed Better Auth using the OptiTech TypeScript SDK.