Scenario: Working with an IoT Domain

This scenario shows how to create an IoT domain and how to add authentication to an IoT domain so you can connect to APEX, ORDS, or to establish a direct database connection to view your IoT data.

Tasks

Create an IoT domain
Optional. Use work requests to check the status of any process when working with an IoT domain.
Depending on where you want to view your IoT data, you need to complete the steps required to configure access to that system. As part of connecting to another system, you need to add authentication credentials to the IoT domain to authenticate to that system:
- Option. Use the Oracle Application Express (APEX) data access command required for connecting to APEX.
- Option. Use the Oracle REST Data Services (ORDS) data access command required for connecting to ORDS.
- Option. Use the Direct database access command if you configure access to view your data directly in the database or Oracle Analytics Cloud.

Before You Begin

To complete this workflow, you must have the following configuration set up:

For administrators: An administrator must add a policy to the compartment where you want to work with the IoT domain to let the specified user or user group create, update, and delete domains in the specific compartment. For more information, see Policy Details for the Internet of Things (IoT) Platform.
You must use an existing IoT domain group or create an IoT domain group before creating an IoT domain.

Note

Oracle recommends creating up to 2 IoT domains in each IoT domain group. The maximum number of IoT domain groups is 5 and maximum number IoT domains is 10 for each region in your tenancy.

Step 1: Create an IoT Domain

Use this oci iot domain create command and the required parameters to create an IoT domain. Replace the <domain-group-OCID> to associate the domain with a domain group. Replace the <compartment-OCID> with the compartment you want to use. You must create the IoT domain in the same region as any related digital twin resources. Optionally, replace <your-display-name> with a name for the IoT domain. Add the --wait-for-state SUCCEEDED parameter to receive the response as the action of creating an IoT domain completes.

oci iot domain create --compartment-id <compartment-OCID> --iot-domain-group-id <domain-group-OCID> --display-name <your-display-name> --wait-for-state SUCCEEDED

This example response shows creating an IoT domain completed successfully.

Action completed. Waiting until the work request has entered state: ('SUCCEEDED',)
{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "id": "<iot-work-request-OCID>",
    "operation-type": "CREATE_IOT_DOMAIN",
    "percent-complete": 100.0,
    "resources": [
      {
        "action-type": "CREATED",
        "entity-type": "iotDomain",
        "entity-uri": "/20250531/iotDomains/<iot-domain-OCID>",
        "identifier": "<iot-domain-OCID>",
        "metadata": null
      }
    ],
    "status": "SUCCEEDED",
    "time-accepted": "2025-09-08T09:47:18.045000+00:00",
    "time-finished": "2025-09-08T09:49:23.201000+00:00",
    "time-started": "2025-09-08T09:47:30.138000+00:00",
    "time-updated": "2025-09-08T09:49:23.201000+00:00"
  },
  "etag": "<unique-id>"
}

Step 2: Get the IoT Domain's Details

Use this command to get the details for an IoT domain:

oci iot domain get --iot-domain-id <iot-domain-OCID>

This example shows the IoT domain is active. Notice the following Identity domain group names and allow Identity domain host parameters are null. This is the expected result as the database connection details are not defined yet. If you want to establish a direct database connection then you must configure the IoT domain's data access to the database in the next step.

"db-allow-listed-identity-group-names": null,

"db-allowed-identity-domain-host": null,

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "data-retention-periods-in-days": {
      "historized-data": 30,
      "raw-command-data": 16,
      "raw-data": 16,
      "rejected-data": 16
    },
    "db-allow-listed-identity-group-names": null,
    "db-allowed-identity-domain-host": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-08T09:47:17.759Z"
      }
    },
    "description": "<your-description>",
    "device-host": "<domain-short-id>.device.iot.<region>.oci.oraclecloud.com",
    "display-name": "<your-display-name>",
    "freeform-tags": {},
    "id": "<iot-domain-OCID>",
    "iot-domain-group-id": "<iot-domain-group-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-08T09:47:17.987000+00:00",
    "time-updated": "2025-09-08T09:49:23.223000+00:00"
  },
  "etag": "<unique-id>"
}

Optional Step: Configure an IoT Domain's Access to Establish a Direct Database Connection

Optionally, if you want to view your IoT data directly in the database or if you want to configure a database connection to view your data in Oracle Analytics Cloud or directly in the database, then use the oci iot domain configure-direct-data-access command to configure an IoT domain's authentication to access the database using the Identity domain group or groups setup during the configuration.

For the <identity-domain-name> parameter enter any of the following options, an <identity-group-name> is either the Identity group or an Identity dynamic group:

If the <identity-group-name> is in the default Identity domain use this format:
<tenancy-OCID:<identity-group-name>
If the <identity-group-name> is not in the default Identity domain, then use this format to specify to Identity domain name for the Identity domain group or the identity domain dynamic group:
<tenancy-OCID>:<identity-domain-name>/<identity-group-name>

oci iot domain configure-direct-data-access --iot-domain-id <iot-domain-OCID> --db-allow-listed-identity-group-names '["<tenancy-OCID>:<identity-group-name>"]'

This example shows multiple identity dynamic groups not in the default Identity domain that are configured and allowed to connect to the database. Use this format if you have an application or user running on a VCN with a dynamic groups configured:

oci iot domain configure-direct-data-access --iot-domain-id <iot-domain-OCID> --db-allow-listed-identity-group-names '["<tenancy-OCID>:<identity-domain-name>/<identity-group-name>", "<tenancy-OCID>:<identity-domain-name>/<identity-group-name>"]'

For a complete list of steps to configure a direct connection to the database, see Scenario: Connecting Directly to the IoT Database or for a complete list of steps to configure access to view your IoT data in Oracle Analytics Cloud see, Scenario: Connecting your IoT Data to Analytics Cloud.

Optional Step: Configure an IoT Domain's Access to Oracle REST Data Services (ORDS)

If you want to use the IoT Data API or view your data in Oracle REST Data Services (ORDS), then you must complete the configure a connection to ORDS.

As part of the configuration, use the oci iot domain configure-ords-data-access command to configure access to the Identity domain host.

Replace the idcs-<idcs-id>.identity.oraclecloud.com with the Identity domain host and the IoT domain's OCID for your environment:

oci iot domain configure-ords-data-access --iot-domain-id <iot-domain-OCID> --db-allowed-identity-domain-host <idcs-unique-id.identity.oraclecloud.com>

For a complete list of steps to configure access to view your data in ORDS, see Scenario: Connecting IoT Data to Oracle REST Data Services (ORDS).

Optional Step: Configure an IoT Domain's Access to APEX

If you want to use the IoT Data API or view your data in Oracle Application Express (APEX), then you must complete the configure a connection to APEX.

As part of the configuration, use the oci iot domain configure-apex-data-access command to configure an IoT domain's access to APEX. Replace the <your-initial-apex-password> and the <iot-domain-OCID> with the values for your environment:

oci iot domain configure-apex-data-access --db-workspace-admin-initial-password "<your-initial-apex-password>" --iot-domain-id <iot-domain-OCID>

For a complete list of steps to configure access to view your data in APEX, see Scenario: Connecting IoT Data to APEX.

Optional Step: Get the IoT Domain's Connection Details

After you configure the data access for an IoT domain, use the oci iot domain get command to get to confirm the connection details for an IoT domain. Replace the <iot-domain-OCID> with the OCID for your IoT domain:

oci iot domain get --iot-domain-id <iot-domain-OCID>

This example response includes the database connection details that are now defined for the IoT domain:

{
  "compartment-id": "<compartment-OCID>",
  "data-retention-periods-in-days": {
    "historized-data": 30,
    "raw-command-data": 16,
    "raw-data": 16,
    "rejected-data": 16
  },
  "db-allow-listed-identity-group-names": [
      "<tenancy-OCID>:<identity-domain-name>/<identity-group-name>"
    ],
  "db-allowed-identity-domain-host": "<idcs-unique-id.identity.oraclecloud.com>",
  "defined-tags": {
    "Oracle-Tags": {
      "CreatedBy": "default/user@oracle.com",
      "CreatedOn": "2025-08-05T18:02:51.633Z"
    }
  },
  "description": "<your-description>",
  "device-host": "<domain-short-id>.device.iot.<region>.oci.oraclecloud.com",
  "display-name": "<your-display-name>",
  "freeform-tags": {},
  "id": "<iot-domain-OCID>",
  "iot-domain-group-id": "<iot-domain-group-OCID>",
  "lifecycle-state": "ACTIVE",
  "system-tags": {},
  "time-created": "2025-08-05T18:02:53.418000+00:00",
  "time-updated": "2025-08-05T18:04:42.585000+00:00"
}

Oracle Cloud Infrastructure Documentation