Oracle Cloud Infrastructure Documentation

Scenario: Connecting IoT Data to Oracle REST Data Services (ORDS)

If you want to use Oracle REST Data Services (ORDS) to view your Internet of Things data, follow these steps to configure access to use ORDS.

The IoT domain database schema contains the metadata and data from the digital twin resources associated to an IoT domain.

There are two ways you can use ORDS:

  • Use the Internet of Things Data API to view your IoT data. For more information, see the IoT Data API documentation.
  • Use ORDS to build and publish custom REST APIs with your own Internet of Things data. Build logic inside your database and expose database operations and objects using CRUD as REST endpoints to build custom RESTful microservices connected to PL/SQL or SQL queries.

IoT data access to ORDS.

After you create an IoT domain group and create an IoT domain you can complete the following steps to configure authentication to view your IoT data in ORDS.

Step 1: Create a Confidential Application for your Identity Domain

In the Identity and Access Management (IAM) service, you need to create a confidential application with client credentials on the target identity domain with administrator permissions.

  1. In your IoT tenancy, sign in as an administrator to the Oracle Cloud Infrastructure Console.
  2. Open the navigation menu and select Identity & Security. Under Identity, select Domains.
  3. Select the name of the identity domain that you want to work with, you may need to change the compartment to find the identity domain you want to use. Or you may need to create a additional identity domain. When you create the confidential application, you must use an identity domain that's not the default domain. You can create additional identity domains to manage different user groups, security requirements, and environments, within a single tenancy. For more information, see Using Multiple Identity Domains and Managing Identity Domains.

    The compartment must be in the same region as the IoT database.

    If you use an existing domain or create a new domain use the following settings:
    • domain type: free
    • Under Domain Administrator turn off Use this email address as the username.
    • On the domain details page, go to the Settings tab, under Domain settings - Locale, select Edit domain settings.
    • To configure the client's access to the signing certificate for the identity domain without the client logging in to the identity domain:

      Under Access signing certificate, turn on the Configure client access option and select Save changes.

      Now, under Domain settings - Access signing certificate you see the Configure client access is enabled.

  4. On the domain details page, select the Integrated applications tab.
  5. Select Add application, select Confidential Application, and then select Launch workflow.
  6. On the Add application details page, enter an application name and a description. Select Submit.

    For a complete list of options, see Adding a Confidential Application.

  7. The integrated application details page opens, from the Actions menu, select Activate. Select Activate application.
  8. Select OAuth configuration tab, select Edit OAuth configuration.
  9. Under Resource server configuration, select Configure this application as a resource server now.
  10. Enter the Primary Audience as /<domain-group-short-id>. Select Submit.

    The data host comes from the IoT domain group and contains the domain group short id.

    To find the data host for the IoT domain group, use the oci iot domain-group get command and replace the <iot-domain-group-OCID> with the OCID for your IoT domain group to get the IoT domain group's details including the domain group's data host with the domain group short id:

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

    In the response, you can find the domain group short id that you need to enter as the primary audience.

    data-host:<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com

    For more information, see Get an IoT Domain Group's Details.

    Note

    /<domain-group-short-id> must be lower-case.
  11. To enable the scope, select Add scopes.
  12. On the Add scope page, enter the Scope using this format:/iot/<domain-short-id>. Select Add.

    The device host comes from the IoT domain and contains the domain short id.

    To find the device host for the IoT domain, use this command and replace the <iot-domain-OCID> with the OCID for your IoT domain to get the IoT domain's details including the domain's device host with the domain short id:

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

    In the response, you can find the domain short id that you need to enter as the scope.

    device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com

    For more information, see Get an IoT Domain's Details.

  13. Under Client configuration, select Configure the application as a client now.
  14. Under Authorization select the following check boxes:
    • Resource owner
    • Client credentials
    • JWT assertion
    • Refresh token
  15. Under Allowed operations, select Introspect to allow access to a token introspection endpoint for your application.
  16. Under Token Insurance policy, select All and then select Submit.
  17. On the OAuth Configuration page, now under Configure application APIs that need to be OAuth protected you see the Primary audience with the /domaingroupshortid and under Scopes the /iot/domainshortid displays.
  18. Under General Information, the Client ID is displayed.
  19. Under Client Secret, the Show secret is displayed with the value hidden.
  20. At the top of the page, select the Users tab, and select Assign users.
  21. Select the check box next to the Username you want to assign to this integrated application. Select Assign.
  22. Select Integrated applications to go back to the domain details page.
  23. On the domain details page, select the User Management tab.
  24. Select Create group.
  25. On the Create group page, enter a name an optional description. Avoid entering any confidential information.
  26. Select the check box next to the user you want to add to group. Select Create.
  27. Select Groups to go back to the domain details page, select the Integrated applications tab.
  28. Select the Integrated application created in the previous step.
  29. Select the Groups tab. Select Assign groups.
  30. Select the check box next to the groups you want to assign access to this integrated application. Select Assign.
  31. On the Domain details page, copy the Domain URL.

  32. Use the oci iot domain configure-ords-data-access command and required parameters to configure an IoT domain's access to Oracle REST Data Services (ORDS).

    Replace <idcs-<unique-id>.identity.oraclecloud.com> with the Domain URL from your domain details page, without the https:// or the port number: 

    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 more information, see Configuring an IoT Domain's Data Access.

  33. Optional. If you want to check the progress of the operation, use the work request command:

    Use the oci iot work-request get command and the required parameter to get the work request details:

    oci iot work-request get --work-request-id <work-request-id>

    For more information, see Getting a Work Request's Details.

  34. Optional. If you want to check the details for an IoT domain, use the oci iot domain get command and the required parameter to get an IoT domain's details:

    oci iot domain get --iot-domain-id <iot-domain-OCID>
    In this example response, you can confirm the data access details for the IoT domain uses the Identity Domain URL format:

    <idcs-<unique-id>.identity.oraclecloud.com>

    For more information, see Getting an IoT Domain's Details.
    {
  "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",
      "CreatedOn": "2025-08-05T18:02:51.633Z"
    }
  },
  "description": <your-description>,
  "device-host": "<domain-short-id>.device.iot.<region>.oci.oraclecloud.com",
  "display-name": "iot-domain-sample",
  "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"
},
"etag": "<unique-id>"

Step 2: Obtain the oAuth Access Token

Obtain an oAuth access token with a password to grant access using the client id and the secret of the integrated application with the user's credentials and scope defined as:

'scope=/<domain-group-short-id>/iot/<domain-short-id>'

Use this CURL command to generate an oAuth access token. Replace the <secret-from-integrated-application> with the secret from the Integrated Application created in the previous step.

For more information, see Using cURL.

For example:
curl --request POST 
    --url 'https://idcs-<identity-hostname>.identity.oraclecloud.com:443/oauth2/v1/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header 'Authorization: Basic <secret-from-integrated-application>' \
    --data 'scope=/<domain-group-short-id>/iot/<domain-short-id>' \
    --data 'grant_type=password' \
    --data 'password=<your-password>' \
    --data username=user@oracle.com
If you are an administrator user, and you need to reset a user's password:
  1. In your IoT tenancy, sign in as an administrator to the Oracle Cloud Infrastructure Console.
  2. Open the navigation menu and select Identity & Security. Under Identity, select Domains.
  3. Find the domain you want to work with, select the domain name.
  4. On the domain details page, select the User Management tab. Find the user you want to reset the password for, at the end of the row select the Actions menu and select Reset Password.

For more information, see Resetting a User's Password.

Now, you can use the IoT ORDS Data API to get IoT data from the database and you can use ORDS to build REST APIs with your IoT data.

Step 3: Invoke the Internet of Things ORDS Data API

If you want to get your Internet of Things data from the database, use this request to invoke the Internet of Things Data API.

This example shows how to get your RAW data: 
curl -H "Authorization: Bearer <token>" \
     -X GET "https://<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com/ords/<domain-short-id>/20250531/rawData?q={\"$and\":[{\"digital_twin_instance_id\":\"<iot-digital-twin-OCID>\"}]}"