---
title: "Create connection"
method: POST
path: "/api/v1/connections"
tags: ["Connections"]
---

# Create connection

`POST /api/v1/connections`

Create a new database connection. The request body varies by dialect - see dialect-specific documentation for required fields.

## Request body

- object — Request body for creating a database connection. Required fields: dialect, name, passwordUnencrypted. Additional fields may be required depending on the dialect.
  - `acceptsLicense` boolean — Acceptance of the license terms. Required for Oracle connections.
  - `allowsUserSpecificTimezones` boolean — Whether to allow users to specify their own timezones
  - `alwaysScopeViewNames` boolean — Whether to always include schema (and catalog) prefixes in generated view names, even for tables in the default schema. Defaults to true for dialects that support multiple catalogs, false otherwise.
  - `authenticationType` string — Authentication type. Dialect-specific; known values are `aws-access-key`, `aws-cross-account-role`, `databricks-oauth-m2m`, `databricks-personal-access-token`, `databricks-oauth-user`, `mssql-sql-authentication`, `mssql-active-directory-password`, `mssql-active-directory-service-principal`, `snowflake-oauth-user`, `snowflake-external-oauth-user`, `snowflake-password`, `snowflake-keypair`, `bigquery-oauth-user`, `bigquery-byo-oauth-user`, `bigquery-service-account`, `bigquery-workload-identity-federation`. Applicable for BigQuery, MSSQL, Snowflake, Databricks, and Athena.
  - `awsRoleArn` string — AWS IAM role ARN. Applicable for Athena only.
  - `baseRole` 'NO_ACCESS' | 'VIEWER' | 'RESTRICTED_QUERIER' | 'QUERIER' | 'MODELER' | 'CONNECTION_ADMIN' — The default role for users accessing the connection
  - `database` string — The default database/catalog to connect to. For BigQuery, this is the project ID. For Athena, this is the data catalog.
  - `defaultSchema` string — The default schema to use. Required for MSSQL.
  - `dialect` 'bigquery' | 'mysql' | 'postgres' | 'redshift' | 'exasol' | 'snowflake' | 'motherduck' | 'mssql' | 'databricks' | 'databricks_lakebase' | 'clickhouse' | 'trino' | 'athena' | 'starrocks' | 'mariadb' | 'oracle' | 'sap_hana', required — The database dialect
  - `enableDbSemanticLayerIntegration` boolean — Enable the dialect-native semantic layer integration. Applicable for Snowflake and Databricks.
  - `enableDbSemanticLayerTopics` boolean — Enable the dialect-native semantic layer topics. Applicable for Snowflake and Databricks.
  - `externalOauthAudience` string — External OAuth audience claim. Applicable for Snowflake.
  - `externalOauthAuthorizationUrl` string, uri — External OAuth authorization URL (must be HTTPS). Applicable for Snowflake.
  - `externalOauthTokenUrl` string, uri — External OAuth token URL (must be HTTPS). Applicable for Snowflake.
  - `host` string — The hostname or IP address of the database server. For Snowflake, provide only the account identifier.
  - `hostOverride` string — Custom Snowflake host (when not using the account identifier). Mutually exclusive with `host`.
  - `includeOtherCatalogs` string — Comma-separated list of other catalogs/databases to include. Only applicable for databases that support multi-catalog queries.
  - `includeSchemas` string — Comma-separated list of schemas to include. Leave empty to include all schemas.
  - `inferRelationshipsFromColumnNames` boolean — Whether to infer relationships from column-name conventions during schema refresh. Defaults to true.
  - `inferRelationshipsFromForeignKeys` boolean — Whether to infer relationships from declared foreign keys during schema refresh. Currently honored for Postgres and Snowflake.
  - `maxBillingBytes` string — Maximum bytes that can be billed for a BigQuery query. Applicable for BigQuery only.
  - `name` string, required — A descriptive name for the connection
  - `oauthClientId` string — OAuth client ID for admin schema refresh. Applicable for Snowflake and Databricks.
  - `oauthClientSecretUnencrypted` string — OAuth client secret for admin schema refresh. Applicable for Snowflake and Databricks.
  - `offloadedSchemas` union — Schemas whose tables should be queried via the offloaded engine. Accepts a comma-separated string or an array of schema names.
    - string
    - string[]
  - `passwordUnencrypted` string, required — The password to authenticate with. For BigQuery, this must be the JSON service account key file content. For Snowflake with keypair authentication, this can be omitted.
  - `port` integer — The port number for the database connection. Not required for Snowflake, MotherDuck, BigQuery, Databricks, and Athena.
  - `privateKey` string — An RSA key for keypair authentication. Omni will automatically add PEM headers if none are provided. Applicable for Snowflake only.
  - `queryTimeoutSeconds` integer — The timeout in seconds for queries. Maximum value is 3600 (1 hour). Only applicable for databases that support query timeouts.
  - `queryTimezone` string — The timezone to use for queries
  - `region` string — Required for BigQuery and Athena connections. For BigQuery, specify a region like "us". For Athena, specify an AWS region like "us-east-1".
  - `scratchSchema` string — Schema to use for data input (upload) tables. If not specified, a suitable default will be chosen.
  - `systemTimezone` string — The timezone to use for the system
  - `trustServerCertificate` boolean — Whether to trust the server certificate. Applicable for MSSQL, Exasol, ClickHouse, Trino, and SAP HANA.
  - `useMachineAuth` boolean — Whether to authenticate using machine credentials (OAuth M2M). Applicable for Athena and Databricks.
  - `username` string — The username to authenticate with. For BigQuery, this is the client email from the service account.
  - `warehouse` string — Required for Snowflake (specify the warehouse) and Databricks (specify the HTTP path). May be omitted for Snowflake OAuth connections, in which case each user's Snowflake default warehouse applies.
  - `wifAudience` string — Full resource name of the workload identity pool provider. Required for BigQuery workload identity federation authentication.
  - `wifServiceAccountEmail` string — Service account to impersonate for BigQuery workload identity federation authentication. When omitted, the federated identity is used directly.

## Response `201`

Connection created successfully

- object — Create connection response
  - `data` string, uuid, required — Created connection ID
  - `success` boolean, required — Whether the operation succeeded

## Other responses

- `400` — Invalid request body or dialect
- `401` — Authentication required
- `403` — Permission denied - admin role required

---

[API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/versions/de7cac8b5983/schema)