Scenario: Create and Manage Secrets for a Digital Twin Instance

If you receive data from a device, then you must use authentication with your digital twin instance. This scenario explains how to use a secret to authenticate a digital twin instance for a device.

The secret is the device password. Using a secret is not recommended for production, only use vault secrets for testing configuration. For production, use a mTLS certificate for digital twin instance authentication.

Tasks

Create a secret
Create or update a digital twin instance authentication ID
Send data
Update and Manage Secrets
Troubleshooting

Before you Begin

Make sure you have the required permissions. An administrator grants access by creating the required policies. For more information, see Prerequisites for the policies required for secrets and Policy Details for the Internet of Things (IoT) Platform for policies required for IoT resources.
Add these policies to the compartment to allow access.
IoT Domain Vault Secret Policy
When you create a digital twin instance if you use a secret for authentication, you need the following policy so an IoT domain can read the secret in a specific vault.
Let any IoT user read secrets in a specific compartment and vault for an IoT domain:
```
Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}
```

To create a secret you need a vault and a key:

Confirm you have a vault, see Listing Vaults, or create a vault. For more information, see Managing Vaults.
Vault Policy
To create a vault your user must add policies to the compartment where you want to create a vault and key.
Let's a group of users manage vaults for a specific compartment.
Allow group <group-name> to manage vaults in compartment <compartment-name>
After you create a vault, you must have an existing hardware-protected, symmetric (HSM) encryption key in Oracle Cloud Infrastructure (OCI). To check if you have a Master encryption key, see Listing Keys. Or to create a new key, that uses HSM protection mode, see Creating a Master Encryption Key.
For more information, see Overview of Vaults and Key Management and Rotating a Key.
Key Policy
Let's a group of users manage keys for a specific compartment.
```
Allow group <group-name> to manage keys in compartment <compartment-name>
```

Step 1: Create a Secret

The plain text secret is the device password. Using a secret is not recommended for production, only use vault secrets for testing configuration.

When you connect to the device use the plain text secret contents. For more information, see Managing Secrets.

On the Secrets list page, select Create Secret. If you need help finding the list page, see Listing Secrets.
Select the Compartment you want to create the secret in. Best practice is to use the compartment with the related IoT resources.
Enter a Name to identify the secret. Avoid entering any confidential information.
Optionally, you can enter a Description to help you identify the secret.
Select the Vault that holds the encryption key. If the vault is in a different compartment, use the Vault compartment selector to specify the compartment of the vault.
Select the master Encryption Key that you want to use to encrypt the secret contents while they're imported to the vault. If the key is in a different compartment, use the Encryption Key compartment selector to specify the compartment of the encryption key.
- The key must be in the same vault as the secret.
- You must select a symmetric key to create the secret. Asymmetric keys aren't supported for secret creation.
Select Manual secret generation to manually provide the secret content. Provide the following:
- In the Secret Type Template, specify the format of the secret contents that you're providing by selecting a template. You can provide secret contents in plain-text when you use the Console to create a vault secret or vault secret version, but secret contents must be base64-encoded before they're sent to the service. The Console automatically encodes plain-text secret contents for you.
- In Secret Contents, enter the contents of the secret. The maximum allowable size for a secret bundle is 25 KB. Later, when you send data to and from a device use this plain text secret as the device password.
In the Secret rotation section, provide the following details:
- Target system type: Select the Target system type as Autonomous AI Database or Function and provide the corresponding Target system id.
- Target system id: The system id is auto populated for the selected Target system type.
- Enable auto rotation: Select the checkbox to turn on automatic rotation.
- Rotation interval: Optionally, select the Rotation interval to update the secret periodically.
Note

If you don't specify target system type and id then, the checkbox isn't enabled for automatic rotation.
To apply a rule to manage how vault secrets are used, in the Rules section, select Another Rule. You can either create a rule regarding the reuse of secret contents across versions of a secret, or you can create a rule specifying when the secret contents expire. For more information about rules, see Secret Rules.
Note

Frequently updating a secret with new secret contents helps keep credentials safer from users with malicious intent. Or, it at least makes shorter the period of time during which compromised credentials can unknowingly be used or disseminated.
Optionally, to apply tags to the secret, select Add tag. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option (you can apply tags later) or ask administrator.
Select Create Secret.
For a complete list of settings, see Create a secret and for best practices see Managing Secrets.

Step 2: Create a Digital Twin Instance with a Secret Authentication ID

To authenticate a device to send data, create a digital twin instance using the --auth-id parameter with the <secret-OCID> created in the previous step. Use this command and parameters to create a digital twin instance that uses a secret to authenticate.

For the --external-key parameter value, replace the <device-username-or-generated> with the device username or if you do not include the external key, it's generated and appears in the response.
Replace the <secret-OCID> with the secret OCID for the secret you want to use.

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <secret-OCID> --external-key <device-username-or-generated>

For a complete list of CLI parameters, see oci iot digital-twin-instance create and see Creating a Digital Twin Instance for more information.

Alternatively, you can update an existing digital twin instance's --auth-id parameter with a secret's OCID.

Step 3: Send Data

Send data to test your configuration.

Device user name: Use the external-key from the digital twin instance as the device user name.
Device password: Is associated to the authentication ID for the digital twin instance. If the digital twin instance uses a vault secret OCID for authentication, then use the plain text secret contents as the device password.
See Getting a Secret's Contents, View a Secret's Details, or View the Contents and Properties of a Secret and the Secret's Versions (Secret Bundles) to find the secret's details.

Using a vault secret as a device password is recommended only for testing, not for production. For production, the digital twin instance should use a mTLS certificate for authentication.

Using Curl
POSIX-style shells: Use this curl command when using bash, zsh, macOS Terminal, Linux, or Git Bash on Windows.
```
curl 
  -u '<digital-twin-instance-external-key>:<device-password>' \
  -H 'Content-Type: text/plain' \
  -d 'sample data 1' \
  'https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic'
```
Windows PowerShell: Use this curl.exe command to send a POST request with a request body using -d.
```
curl.exe -u "<digital-twin-instance-external-key>:<device-password>" `
  -H "Content-Type: text/plain" `
  -d "sample data 1" `
  "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"
```
When you complete Step 4: Create a Digital Twin Instance, if you defined the external key parameter value with quotes, you must include the quotes when you send data: "external-key". For quoting best practices, see Troubleshooting.
Use any MQTT client, this example uses MQTTX with the following settings.
1. Download and set up MQTTX follow these instructions, see Getting Started with MQTTX. Open MQTTX.
2. Select + New Connection, to create a new connection.
3. Enter the external key <unique-id> value as the Username. You can find the external key in the oci iot digital-twin-instance create response, from the previous Step 4: Create a Digital Twin Instance:
```
"external-key": "<unique-id>"
```
4. Enter the device password. If you are testing with a vault secret, use the plain text secret contents. For a secure production environment, use a mTLS certificate.
5. Enter the Host. Select the mqtts:// protocol from the host drop-down list and enter the device host: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com from the IoT domain.
6. Enter the port, for example: 8883
  Note
  
  Currently, MQTT Secure (MQTTS) is only supported using port 8883.
7. Turn on the toggle SSL/TLS.
8. Turn on the toggle SSL Secure.
9. For the Certificate, select the CA signed server certificate option.
10. When you configure the MQTTX connection, choose the session behavior intentionally. Use clean session for a stateless reconnect, or disable clean session with a stable client ID for a persistent session that resumes existing subscriptions. The Last-Will-Retain setting controls only whether the Last Will message is retained and does not control subscription persistence.
11. Set the Last Will QoS to 1.
12. Select Connect.
After you finish these steps, you have a digital twin instance in the IoT platform that can receive data from a device.

Update a Secret or Create a New Secret

Secret Rotation Best Practices

Use a defined lifecycle for rotating device credentials stored in OCI Vault secrets. Rotate secret contents regularly to reduce credential exposure and support audit/compliance requirements.

Recommended baseline policy: rotate secret contents every 90 to 180 days, review rotation cadence annually, and rotate immediately when a security event occurs.

Rotate secret contents immediately when risk changes, such as:

Suspected secret compromise or unauthorized access.
A device or integration security incident.
Policy or compliance changes that require a shorter credential lifetime.

When possible, use automation for predictable rotation windows and manual rotation for emergency events.

Update an Existing Secret (Same Secret OCID)

Use the update an existing secret for rotation this option keeps the same secret OCID and maintains the lifecycle:

Using the Console: Create a new version of the secret, then edit the secret properties if needed.
Using the CLI or API: Update the secret contents; OCI automatically creates a new secret version.
Zero-downtime behavior: The secret OCID stays the same, so the digital twin instance can continue using the existing --auth-id.
Rollback readiness: Prior versions remain available (unless deleted), for a rollback if needed.

Create a New Secret (New Secret OCID)

Use a new secret when you need a new secret OCID with an independent lifecycle. Typical use cases include:

Unique credentials: One secret per device or per digital twin instance.
Environment separation: Different policies, compartments, vaults, or governance boundaries.
New ownership or naming requirements: Clean separation for operations and auditing.

After creating a new secret, update the digital twin instance with the new --auth-id.

Validation Checklist After Secret Rotation

Confirm the new secret version is active and retrievable.
Verify the digital twin instance still resolves the configured --auth-id.
Validate device authentication and data flow over HTTPS or MQTTS.
Record rotation date, secret version, and test results for audit evidence.

For additional lifecycle controls, see Updating a Secret's Rules, Secret Rules, and Secret FAQs.

Troubleshooting Authorization Errors

404 error - Service error: NotAuthorizedOrNotFound

If you receive an IoT service error message related to authorization, it could be related to a secret or the authentication ID --auth-id parameter on the digital twin instance. Confirm these values are correct:

Confirm the digital twin instance --auth-id parameter contains the correct secret OCID.
Confirm you have the policy in the corresponding compartment for the associated vault, secret, or IoT resource.
In the Secret Management service, confirm the secret is active, list secrets or view a secret's contents.

If you create a digital twin instance with this 404 response:

...ServiceError:
{
    "client_version": "Oracle-PythonSDK/2.161.0, Oracle-PythonCLI/3.68.0",
    "code": "NotAuthorizedOrNotFound",
    "logging_tips": "Please run the OCI CLI command using --debug flag to find more debug information.",
    "message": "Resource Auth id with OCID [ocid1.vaultsecret.oc1.iad.unique-id] not found",
    "opc-request-id": "unique-id",
    "operation_name": "create_digital_twin_instance",
    "request_endpoint": "POST https://iot.region.oci.oraclecloud.com/20250531/digitalTwinInstances",
    "status": 404...

Typically it's for one of these reasons:

Resource does not exist. To confirm the secrets you have access to, use the oci secrets secret-bundle get command, see remedy below.

Use this command to confirm the secrets you have access to. To access your secrets from the Console or API, see List the secrets.

oci secrets secret-bundle get --secret-id ocid1.vaultsecret.oc1.iad.unique-id

You do not have the correct policy for the IoT domain to read the vault secret credential. Add this policy to the compartment for the vault so the IoT domain can read secrets in a specific vault.

Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}

The secret may not be active.

Oracle Cloud Infrastructure Documentation