Custom user databases

Manage connections to your own user database with developer credentials. Your plan must include this feature. Test a connection and its action scripts before activation. Only one connection can be active in a workspace. Test calls run against the database you configure.

API conventions · All endpoints · Schemas

`/e/v1/developer/custom-databases/`

Manage an optional external user database connection.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

Optional query workspace UUID; returns connection metadata array.

Related schemas: CustomDatabaseConnection.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "workspace": "11111111-1111-4111-8111-111111111111",
    "name": "Example",
    "description": "EXAMPLE_DESCRIPTION",
    "database_type": "postgresql",
    "sync_mode": "EXAMPLE_SYNC_MODE",
    "connection_string_masked": "EXAMPLE_CONNECTION_STRING_MASKED",
    "connection_config": {},
    "entities_config": {},
    "schema_mapping": {},
    "cache_ttl_seconds": 1,
    "is_active": true,
    "connection_status": "unknown",
    "last_connection_test": "2026-10-26T12:00:00Z",
    "last_connection_error": "EXAMPLE_LAST_CONNECTION_ERROR",
    "migration_started_at": "2026-10-26T12:00:00Z",
    "migration_completed_at": "2026-10-26T12:00:00Z",
    "migrated_users_count": 1,
    "developer_id": "EXAMPLE_DEVELOPER_ID",
    "scripts_count": 1,
    "created_at": "2026-10-26T12:00:00Z",
    "updated_at": "2026-10-26T12:00:00Z"
  }
]

POST

Required developer-token scope: write_custom_databases.

Required workspace UUID, name string and database_type choice. Supply connection_string to make the connection usable. Optional connection_config/entities_config/schema_mapping objects and cache_ttl_seconds integer; exact field constraints are in the schema. Plan feature and workspace permission required.

Request / response schema: CustomDatabaseConnection.

Related schemas: CustomDatabaseConnection.

Example request body:

{
  "workspace": "11111111-1111-4111-8111-111111111111",
  "name": "Local external users",
  "database_type": "postgresql",
  "connection_string": "postgresql://user:[email protected]:5432/users"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "description": "EXAMPLE_DESCRIPTION",
  "database_type": "postgresql",
  "sync_mode": "EXAMPLE_SYNC_MODE",
  "connection_string_masked": "EXAMPLE_CONNECTION_STRING_MASKED",
  "connection_config": {},
  "entities_config": {},
  "schema_mapping": {},
  "cache_ttl_seconds": 1,
  "is_active": true,
  "connection_status": "unknown",
  "last_connection_test": "2026-10-26T12:00:00Z",
  "last_connection_error": "EXAMPLE_LAST_CONNECTION_ERROR",
  "migration_started_at": "2026-10-26T12:00:00Z",
  "migration_completed_at": "2026-10-26T12:00:00Z",
  "migrated_users_count": 1,
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "scripts_count": 1,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z"
}

`/e/v1/developer/custom-databases/test-connection/`

Manage an optional external user database connection.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

POST

Required developer-token scope: write_custom_databases.

Required JSON database_type (postgresql/mysql/mongodb) and connection_string string. Tests a connection before saving it; inspect success/message/latency_ms even when status is 200.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`database_type`	`not supplied`
body	`connection_string`	`not supplied`

Related schemas: CustomDatabaseConnection.

Example request body:

{
  "database_type": "postgresql",
  "connection_string": "postgresql://user:[email protected]:5432/users"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "success": false,
  "message": "EXAMPLE_MESSAGE",
  "latency_ms": "EXAMPLE_LATENCY_MS"
}

400 — json

{
  "error": "database_type and connection_string are required"
}

400 — json

{
  "error": "Invalid database_type. Must be one of: EXAMPLE"
}

`/e/v1/developer/custom-databases/{id}/`

Manage an optional external user database connection.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

Required path id UUID; returns connection metadata.

Path parameters: id (uuid, required).

Related schemas: CustomDatabaseConnection.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "description": "EXAMPLE_DESCRIPTION",
  "database_type": "postgresql",
  "sync_mode": "EXAMPLE_SYNC_MODE",
  "connection_string_masked": "EXAMPLE_CONNECTION_STRING_MASKED",
  "connection_config": {},
  "entities_config": {},
  "schema_mapping": {},
  "cache_ttl_seconds": 1,
  "is_active": true,
  "connection_status": "unknown",
  "last_connection_test": "2026-10-26T12:00:00Z",
  "last_connection_error": "EXAMPLE_LAST_CONNECTION_ERROR",
  "migration_started_at": "2026-10-26T12:00:00Z",
  "migration_completed_at": "2026-10-26T12:00:00Z",
  "migrated_users_count": 1,
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "scripts_count": 1,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z"
}

PATCH

Required developer-token scope: write_custom_databases.

Partial connection schema; connection_string is write-only/encrypted. Required path id UUID.

Path parameters: id (uuid, required).

Request / response schema: CustomDatabaseConnection.

Related schemas: CustomDatabaseConnection.

Example request body:

{
  "name": "Updated connection"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "description": "EXAMPLE_DESCRIPTION",
  "database_type": "postgresql",
  "sync_mode": "EXAMPLE_SYNC_MODE",
  "connection_string_masked": "EXAMPLE_CONNECTION_STRING_MASKED",
  "connection_config": {},
  "entities_config": {},
  "schema_mapping": {},
  "cache_ttl_seconds": 1,
  "is_active": true,
  "connection_status": "unknown",
  "last_connection_test": "2026-10-26T12:00:00Z",
  "last_connection_error": "EXAMPLE_LAST_CONNECTION_ERROR",
  "migration_started_at": "2026-10-26T12:00:00Z",
  "migration_completed_at": "2026-10-26T12:00:00Z",
  "migrated_users_count": 1,
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "scripts_count": 1,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z"
}

DELETE

Required developer-token scope: write_custom_databases.

No body; delete this connection configuration.

Path parameters: id (uuid, required).

Related schemas: CustomDatabaseConnection.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

204 — json

No response body.

`/e/v1/developer/custom-databases/{id}/test/`

Manage an optional external user database connection.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

POST

Required developer-token scope: write_custom_databases.

No body; tests the saved connection and records status.

Path parameters: id (uuid, required).

Related schemas: ConnectionTest, CustomDatabaseConnection.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "success": false,
  "message": "An unexpected error occurred",
  "latency_ms": "EXAMPLE_LATENCY_MS"
}

`/e/v1/developer/custom-databases/{id}/activate/`

Manage an optional external user database connection.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

POST

Required developer-token scope: write_custom_databases.

No body. Requires feature entitlement, a successful connection test and no other active connection in the workspace. May create/update schema and scripts in the external database.

Path parameters: id (uuid, required).

Related schemas: CustomDatabaseConnection.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "status": "activated",
  "scripts_created": [],
  "scripts_updated": [],
  "schema_created": "EXAMPLE_SCHEMA_CREATED"
}

400 — json

{
  "error": "Cannot activate this database. 'EXAMPLE' is already active in this workspace. Please deactivate it first.",
  "active_database_id": "EXAMPLE_ACTIVE_DATABASE_ID",
  "active_database_name": "EXAMPLE_ACTIVE_DATABASE_NAME"
}

400 — json

{
  "error": "Connection must pass a successful test before activation"
}

`/e/v1/developer/custom-databases/{id}/deactivate/`

Manage an optional external user database connection.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

POST

Required developer-token scope: write_custom_databases.

No body; switches off routing through this connection. Does not copy users into the SyAuth user store.

Path parameters: id (uuid, required).

Related schemas: CustomDatabaseConnection.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "status": "deactivated"
}

`/e/v1/developer/custom-databases/{id}/stats/`

Manage an optional external user database connection.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

No body; returns migrated_users_count and operation/latency summaries for last_24h and last_7d.

Path parameters: id (uuid, required).

Related schemas: CustomDatabaseConnection.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "migrated_users_count": 1,
  "last_24h": {
    "total_operations": "EXAMPLE_TOTAL_OPERATIONS",
    "successful_operations": "EXAMPLE_SUCCESSFUL_OPERATIONS",
    "avg_latency_ms": "EXAMPLE_AVG_LATENCY_MS"
  },
  "last_7d": {
    "total_operations": "EXAMPLE_TOTAL_OPERATIONS",
    "successful_operations": "EXAMPLE_SUCCESSFUL_OPERATIONS"
  }
}

`/e/v1/developer/custom-databases/{connection_id}/scripts/`

Manage/test external-database action scripts.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

No body. Returns scripts for connection_id.

Path parameters: connection_id (uuid, required).

Related schemas: CustomDatabaseScript.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "connection": "11111111-1111-4111-8111-111111111111",
    "script_type": "login",
    "script_language": "sql",
    "script_content": "EXAMPLE_SCRIPT_CONTENT",
    "is_enabled": true,
    "last_execution_at": "2026-10-26T12:00:00Z",
    "execution_count": 1,
    "success_count": 1,
    "error_count": 1,
    "avg_execution_time_ms": 1.0,
    "success_rate": "EXAMPLE_SUCCESS_RATE",
    "created_at": "2026-10-26T12:00:00Z",
    "updated_at": "2026-10-26T12:00:00Z"
  }
]

POST

Required developer-token scope: write_custom_databases.

Required script_type and script_content; optional script_language (sql/python), is_enabled. Connection is supplied by the path; choose script type from the schema choices. Use the templates endpoint for database-specific statements.

Path parameters: connection_id (uuid, required).

Request / response schema: CustomDatabaseScript, ScriptTest.

Related schemas: CustomDatabaseScript.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "connection": "11111111-1111-4111-8111-111111111111",
  "script_type": "login",
  "script_language": "sql",
  "script_content": "EXAMPLE_SCRIPT_CONTENT",
  "is_enabled": true,
  "last_execution_at": "2026-10-26T12:00:00Z",
  "execution_count": 1,
  "success_count": 1,
  "error_count": 1,
  "avg_execution_time_ms": 1.0,
  "success_rate": "EXAMPLE_SUCCESS_RATE",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z"
}

`/e/v1/developer/custom-databases/{connection_id}/scripts/templates/`

Manage/test external-database action scripts.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

No body. Returns script templates for the connection database type.

Path parameters: connection_id (uuid, required).

Related schemas: CustomDatabaseScript.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{}

`/e/v1/developer/custom-databases/{connection_id}/scripts/{id}/`

Manage/test external-database action scripts.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

No body. Returns selected script.

Path parameters: connection_id (uuid, required), id (uuid, required).

Related schemas: CustomDatabaseScript.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "connection": "11111111-1111-4111-8111-111111111111",
  "script_type": "login",
  "script_language": "sql",
  "script_content": "EXAMPLE_SCRIPT_CONTENT",
  "is_enabled": true,
  "last_execution_at": "2026-10-26T12:00:00Z",
  "execution_count": 1,
  "success_count": 1,
  "error_count": 1,
  "avg_execution_time_ms": 1.0,
  "success_rate": "EXAMPLE_SUCCESS_RATE",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z"
}

PATCH

Required developer-token scope: write_custom_databases.

Partial script schema; script_content must be nonempty and pass forbidden-pattern validation.

Path parameters: connection_id (uuid, required), id (uuid, required).

Request / response schema: CustomDatabaseScript.

Related schemas: CustomDatabaseScript.

Example request body:

{
  "script_content": "SELECT * FROM users WHERE email = %(email)s"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "connection": "11111111-1111-4111-8111-111111111111",
  "script_type": "login",
  "script_language": "sql",
  "script_content": "EXAMPLE_SCRIPT_CONTENT",
  "is_enabled": true,
  "last_execution_at": "2026-10-26T12:00:00Z",
  "execution_count": 1,
  "success_count": 1,
  "error_count": 1,
  "avg_execution_time_ms": 1.0,
  "success_rate": "EXAMPLE_SUCCESS_RATE",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z"
}

DELETE

Required developer-token scope: write_custom_databases.

No body; removes the selected script.

Path parameters: connection_id (uuid, required), id (uuid, required).

Related schemas: CustomDatabaseScript.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

204 — json

No response body.

`/e/v1/developer/custom-databases/{connection_id}/scripts/{id}/test/`

Manage/test external-database action scripts.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

POST

Test the saved script against its real target. login accepts email/password; get_user accepts email; get_user_by_id requires user_id; generic execution accepts params object. Defaults are shown in the request-field table.

Path parameters: connection_id (uuid, required), id (uuid, required).

Request / response schema: ScriptTest.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`email`	`'[email protected]'`
body	`password`	`'testpass'`
body	`user_id`	`not supplied`
body	`params`	`{}`

Related schemas: CustomDatabaseScript, ScriptTest.

Example request body:

{
  "email": "[email protected]",
  "password": "ExamplePass!7264X"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "success": true,
  "result": {},
  "execution_time_ms": "EXAMPLE_EXECUTION_TIME_MS",
  "error": "EXAMPLE_ERROR"
}

`/e/v1/developer/custom-databases/{connection_id}/logs/`

Read external-database operation logs.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

List filters: optional operation, status, limit integer default 100. Path connection_id scopes the logs; detail adds log id. No writes.

Path parameters: connection_id (uuid, required).

Request / response schema: CustomDatabaseSyncLog.

Related schemas: CustomDatabaseSyncLog.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "connection": "11111111-1111-4111-8111-111111111111",
    "connection_name": "EXAMPLE_CONNECTION_NAME",
    "operation": "login",
    "entity_type": "EXAMPLE_ENTITY_TYPE",
    "entity_id": "EXAMPLE_ENTITY_ID",
    "status": "success",
    "error_message": "EXAMPLE_ERROR_MESSAGE",
    "error_code": "EXAMPLE_ERROR_CODE",
    "execution_time_ms": 1,
    "request_id": "EXAMPLE_REQUEST_ID",
    "ip_address": "EXAMPLE_IP_ADDRESS",
    "created_at": "2026-10-26T12:00:00Z"
  }
]

`/e/v1/developer/custom-databases/{connection_id}/logs/{id}/`

Read external-database operation logs.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

List filters: optional operation, status, limit integer default 100. Path connection_id scopes the logs; detail adds log id. No writes.

Path parameters: connection_id (uuid, required), id (uuid, required).

Request / response schema: CustomDatabaseSyncLog.

Related schemas: CustomDatabaseSyncLog.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "connection": "11111111-1111-4111-8111-111111111111",
  "connection_name": "EXAMPLE_CONNECTION_NAME",
  "operation": "login",
  "entity_type": "EXAMPLE_ENTITY_TYPE",
  "entity_id": "EXAMPLE_ENTITY_ID",
  "status": "success",
  "error_message": "EXAMPLE_ERROR_MESSAGE",
  "error_code": "EXAMPLE_ERROR_CODE",
  "execution_time_ms": 1,
  "request_id": "EXAMPLE_REQUEST_ID",
  "ip_address": "EXAMPLE_IP_ADDRESS",
  "created_at": "2026-10-26T12:00:00Z"
}

`/e/v1/developer/custom-databases/{connection_id}/mappings/`

Read external/internal user mapping metadata.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_custom_databases.

No body; connection_id scopes the list.

Path parameters: connection_id (uuid, required).

Request / response schema: CustomDatabaseUserMapping.

Related schemas: CustomDatabaseUserMapping.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "connection": "11111111-1111-4111-8111-111111111111",
    "local_user_id": "11111111-1111-4111-8111-111111111111",
    "external_user_id": "EXAMPLE_EXTERNAL_USER_ID",
    "is_migrated": true,
    "last_synced_at": "2026-10-26T12:00:00Z",
    "sync_direction": "to_external",
    "created_at": "2026-10-26T12:00:00Z",
    "updated_at": "2026-10-26T12:00:00Z"
  }
]

/e/v1/developer/custom-databases/​

GET​

POST​

/e/v1/developer/custom-databases/test-connection/​

POST​

/e/v1/developer/custom-databases/{id}/​

GET​

PATCH​

DELETE​

/e/v1/developer/custom-databases/{id}/test/​

POST​

/e/v1/developer/custom-databases/{id}/activate/​

POST​

/e/v1/developer/custom-databases/{id}/deactivate/​

POST​

/e/v1/developer/custom-databases/{id}/stats/​

GET​

/e/v1/developer/custom-databases/{connection_id}/scripts/​

GET​

POST​

/e/v1/developer/custom-databases/{connection_id}/scripts/templates/​

GET​

/e/v1/developer/custom-databases/{connection_id}/scripts/{id}/​

GET​

PATCH​

DELETE​

/e/v1/developer/custom-databases/{connection_id}/scripts/{id}/test/​

POST​

/e/v1/developer/custom-databases/{connection_id}/logs/​

GET​

/e/v1/developer/custom-databases/{connection_id}/logs/{id}/​

GET​

/e/v1/developer/custom-databases/{connection_id}/mappings/​

GET​

`/e/v1/developer/custom-databases/`

GET

POST

`/e/v1/developer/custom-databases/test-connection/`

POST

`/e/v1/developer/custom-databases/{id}/`

GET

PATCH

DELETE

`/e/v1/developer/custom-databases/{id}/test/`

POST

`/e/v1/developer/custom-databases/{id}/activate/`

POST

`/e/v1/developer/custom-databases/{id}/deactivate/`

POST

`/e/v1/developer/custom-databases/{id}/stats/`

GET

`/e/v1/developer/custom-databases/{connection_id}/scripts/`

GET

POST

`/e/v1/developer/custom-databases/{connection_id}/scripts/templates/`

GET

`/e/v1/developer/custom-databases/{connection_id}/scripts/{id}/`

GET

PATCH

DELETE

`/e/v1/developer/custom-databases/{connection_id}/scripts/{id}/test/`

POST

`/e/v1/developer/custom-databases/{connection_id}/logs/`

GET

`/e/v1/developer/custom-databases/{connection_id}/logs/{id}/`

GET

`/e/v1/developer/custom-databases/{connection_id}/mappings/`

GET