> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up connection environments with the API

> Configure dev and prod connection environments with the API.

[All guides](https://docs.omni.co/guides.md)

Progress

%

Category

api

Last updated

November 2026

# Set up connection environments with the API

Connection environments allow you to configure multiple database connections based on [user attributes](https://docs.omni.co/administration/users/attributes). This is useful for scenarios where you need to provide different database access based on user roles or environments.

In this guide, we'll walk you through creating development and production connection environments.

## Requirements

To follow the steps in this guide, you'll need:

* An [Omni API key](https://docs.omni.co/api/authentication.md)
* **Connection Admin** permissions on an existing Omni database connection

## Steps

**1. Create the base connection**

This is the default connection. Omni uses it for users whose user attribute value is one of the base connection's default values. Use the [Create a connection API](https://docs.omni.co/api/connections/create-connection.md) to create the connection.

In this example, this would be a connection to your **development** database:

```bash title="POST /api/v1/connections" theme={null}
curl -L -X POST 'https://blobsrus.omniapp.co/api/v1/connections' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "dialect": "postgres",
  "name": "Postgres (Development)",
  "host": "postgres-dev.my-org.com",
  "port": 5432,
  "database": "dev",
  "username": "dbuser",
  "passwordUnencrypted": "mypassword",
  "includeSchemas": ["public"],
  "queryTimeoutSeconds": 900
}'
```

**2. Create environment connections**

Environment conditions are additional connections with the same dialect as the base connection. Use the [Create a connection API](https://docs.omni.co/api/connections/create-connection.md) to create the connection(s).

In this example, this would be a connection to your **production** database:

```bash title="POST /api/v1/connections" theme={null}
curl -L -X POST 'https://blobsrus.omniapp.co/api/v1/connections' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "dialect": "postgres",
  "name": "Postgres (Production)",
  "host": "postgres-prod.my-org.com",
  "port": 5432,
  "database": "prod",
  "username": "dbuser",
  "passwordUnencrypted": "mypassword",
  "includeSchemas": ["public"],
  "queryTimeoutSeconds": 900
}'
```

**3. Connect the base and environment connections**

Use the [Create connection environments API](https://docs.omni.co/api/connection-environments/create-connection-environments.md) to associate the base connection with the environment connections. Provide the following:

* `baseConnectionId` - The ID of the base connection. In this example, that's your **development** database.
* `environmentConnectionIds` - The ID(s) of the connection environments. In this example, that's your **production** database.

```json title="POST /api/v1/connection-environments" theme={null}
curl -L -X POST 'https://blobsrus.omniapp.co/api/v1/connection-environments' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "baseConnectionId": "c0f12353-4817-4398-bcc0-d501e6dd2f64",
  "environmentConnectionIds": ["b31f9c9f-208d-48a2-9ae3-ff80f2c79fed"]
}'
```

**4. Configure the base connection user attribute**

Use the [Update a connection API](https://docs.omni.co/api/connections/update-connection.md) to specify which user attribute will be used to determine the connection environment.

In this example, configure the base connection to use the `environment` user attribute and set its default values to `["dev"]`:

```json title="PATCH /api/v1/connections/:id" theme={null}
curl -L -X PATCH 'https://blobsrus.omniapp.co/api/v1/connections/c0f12353-4817-4398-bcc0-d501e6dd2f64' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "environmentUserAttribute": {
    "attributeName": "environment",
    "defaultValues": ["dev"]
  }
}'
```

To remove the user attribute from the base connection, set `environmentUserAttribute` to `null`.

> [!NOTE]
>
> Connection responses show these settings as `userAttributeNameForConnectionEnvironments` and `userAttributeValuesForDefaultEnvironment`. Don't use those field names in the update request. The endpoint rejects them.

**5. Define user attribute values for environments**

Use the [Update connection environment user attributes API](https://docs.omni.co/api/connection-environments/update-connection-environment.md) to specify which user attribute values will trigger the use of each environment connection.

In this example, set the user attribute values for the **production** environment connection to `prod`:

```json title="PUT /api/v1/connection-environments/:id" theme={null}
curl -L -X PUT 'https://blobsrus.omniapp.co/api/v1/connection-environments/b31f9c9f-208d-48a2-9ae3-ff80f2c79fed' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "userAttributeValues": ["prod"]
}'
```

Now, users with the `environment` attribute set to `prod` use the production database, and users with the `environment` attribute set to `dev` use the development database.

> [!WARNING]
>
> Omni doesn't fall back to the base connection for other values. If a user's attribute value isn't one of the base connection's default values or an environment's values, the user's queries fail with an error. If the attribute has more than one value, Omni uses only the first value. Refer to [Dynamic environments](https://docs.omni.co/connect-data/dynamic-environments.md) for more information.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.