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.
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.
- In your IoT tenancy, sign in as an administrator to the Oracle Cloud Infrastructure Console.
- Open the navigation menu and select Identity & Security. Under Identity, select Domains.
- 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.
- On the domain details page, select the Integrated applications tab.
- Select Add application, select Confidential Application, and then select Launch workflow.
- 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.
- The integrated application details page opens, from the Actions menu, select Activate. Select Activate application.
- Select OAuth configuration tab, select Edit OAuth configuration.
- Under Resource server configuration, select Configure this application as a resource server now.
- 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. - To enable the scope, select Add scopes.
- 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.
- Under Client configuration, select Configure the application as a client now.
- Under Authorization select the following check boxes:
- Resource owner
- Client credentials
- JWT assertion
- Refresh token
- Under Allowed operations, select Introspect to allow access to a token introspection endpoint for your application.
- Under Token Insurance policy, select All and then select Submit.
- 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. - Under General Information, the Client ID is displayed.
- Under Client Secret, the Show secret is displayed with the value hidden.
- At the top of the page, select the Users tab, and select Assign users.
- Select the check box next to the Username you want to assign to this integrated application. Select Assign.
- Select Integrated applications to go back to the domain details page.
- On the domain details page, select the User Management tab.
- Select Create group.
- On the Create group page, enter a name an optional description. Avoid entering any confidential information.
- Select the check box next to the user you want to add to group. Select Create.
- Select Groups to go back to the domain details page, select the Integrated applications tab.
- Select the Integrated application created in the previous step.
- Select the Groups tab. Select Assign groups.
- Select the check box next to the groups you want to assign access to this integrated application. Select Assign.
- On the Domain details page, copy the Domain URL.
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.
- 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.
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:In this example response, you can confirm the data access details for the IoT domain uses the Identity Domain URL format:oci iot domain get --iot-domain-id <iot-domain-OCID>
<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.
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
- In your IoT tenancy, sign in as an administrator to the Oracle Cloud Infrastructure Console.
- Open the navigation menu and select Identity & Security. Under Identity, select Domains.
- Find the domain you want to work with, select the domain name.
- 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.
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>\"}]}"