Oracle Cloud Infrastructure Documentation

Workflow: Re-enroll an Oracle Radio Mobile Application

Restore a Radio mobile application's registration after a reset or reinstallation, or replace its enrollment to connect to a different server.

Use this workflow when the supported Radio mobile application no longer has its Radio device ID, or your administrator provides replacement enrollment for a different server. A Radio administrator creates a new one-time registration, the intended user signs in again, and the application stores the Radio device ID returned by the completed registration.

For re-enrollment started from Settings, follow the Android steps or iOS steps before continuing with authentication. Re-enrollment is not a routine fix for a temporary connection or refresh failure; first review session recovery.

Re-register an existing Radio device record when that record should be retained. Create a new registration when the application should use a new device record. The application must use the device ID returned by the current registration; it must not assume that an earlier ID still applies.

This workflow uses a one-time grant. A still-active reusable registration can enroll the same intended user again, but always creates a new device record. It does not restore an existing device ID.

Before You Begin

Confirm the following requirements:

  • The intended user is active in the Public Safety and Security instance's Identity Domain and enabled in Radio.
  • The Radio administrator has radio.enrollment.manage and radio.device.manage.
  • The intended user has a supported Radio mobile application that can provide an opaque advertising ID for its installation.
  • The administrator knows whether to retain an existing Radio device record or create a new record for the installation.

Step 1: Create the Replacement Registration

  1. In Radio, select Devices icon Devices.
  2. Choose the registration path:
    • To retain an existing Radio device record, find the device and select Re-register.
    • To create a device record for a new application installation, select Register device.
  3. Select the intended enabled Radio user. For a new device record, also enter a display name.
  4. For Expires at, enter a future date and time after which the registration value can't be used.
  5. For a new device record, leave Reusable QR code cleared for this one-time workflow. Select Create QR code.
  6. Give the new QR value to only the intended user, and then select Done.

The new value is short-lived and can be used only once. An expired, consumed, or revoked registration value can't be reused. For the existing-device path, see Re-registering an Oracle Radio Device.

Re-enroll from Android Settings

Use these steps when you need to replace the Android application's enrollment or server configuration. Have the intended replacement QR code available first.

  1. Open Settings and choose the re-enrollment action.
  2. Read the confirmation, then select Re-enroll only when ready to end your current session. The app stops current radio activity and clears the signed-in session before showing the enrollment instructions.
  3. Continue from the enrollment instructions and scan the replacement QR code. Review the displayed server details and confirm only if they match the registration provided by your administrator.
  4. Sign in as the intended user and allow the app to complete enrollment. Verify your identity and connection before returning to radio work.
Important

After confirming re-enrollment in Settings, Cancel or Back returns to signed-out Login, not to your previous signed-in session. The server configuration is replaced only after you validate and confirm the replacement QR code.

If the app reports that it can't prepare the device for re-enrollment, retry the action. If the failure persists, contact your administrator with the app version and nonsensitive error text. See re-enrollment help.

Re-enroll from iOS Settings

Use these steps when you need to replace your iPhone or iPad's Radio enrollment or connect to a different server. Have the intended replacement QR code available first.

  1. Open Settings and select Re-enroll Device.
  2. Read the confirmation, then select Re-enroll when ready to disconnect, scan a new QR code, and sign in again.
  3. Keep Oracle Radio open while it disconnects. If it reports that the radio is still disconnecting, wait and try Re-enroll Device again. Don't clear application data as a workaround.
  4. When enrollment opens, scan the intended replacement QR code and sign in as the intended user. Verify your identity, server, and channel connection.
  5. Review your reception settings. Re-enrollment turns off background reception, Bluetooth PTT, and the lock-screen Action Button. Enable the controls you need again; Bluetooth pairing is retained.

If preparation fails, follow the re-enrollment help.

Step 2: Authenticate the Reset or Reinstalled Application

  1. In the reset or reinstalled Radio mobile application, scan the new QR value.
  2. Read the Radio base URL, Identity Domain URL, public mobile client ID, authorization scope, and new one-time registration grant from the QR value.
  3. Create new authorization state, nonce, and PKCE verifier and S256 challenge values.
  4. Start the Identity Domain Authorization Code flow with the public mobile client ID and supported callback. Request openid, offline_access, and the authorization scope supplied in the new QR value.
  5. Use the supplied authorization scope exactly as provided. Don't reuse, construct, normalize, or hard-code a value from earlier installation state.
  6. Have the intended user sign in, allow the browser to return through the application's supported callback, and validate the callback state and returned tokens.

For the complete authentication sequence and token-handling requirements, see Step 2: Authenticate the Mobile Application.

Step 3: Complete Re-enrollment

  1. Run completeDeviceRegistration with the new one-time registration grant, the installation's opaque advertising ID, and the current Identity Domain bearer access token.
  2. Confirm that Radio returns the expected registered device.
  3. Store the returned Radio device ID as the current application-installation state.
  4. Don't assume that the returned ID matches the prior device ID unless the administrator re-registered the existing Radio device record.

Protect the current OAuth tokens and Radio device ID. The device ID doesn't authenticate or authorize the user. Every Radio REST request still requires a valid bearer access token. For WebSocket, send the access token in AUTH when authenticating or renewing the session.

Step 4: Verify the Restored Installation

  1. Send an authenticated heartbeatRadioDevice request for the returned Radio device ID.
  2. Construct the WebSocket URL from the current registration descriptor's radioBaseUrl. Use wss, the same hostname and any explicitly supplied port, and /ws/radio. Open the connection with the returned device ID in the X-Oracle-Radio-Device-Id header.
  3. After the connection opens, send the current bearer access token in AUTH and wait for AUTH_SUCCESS. The enabled user needs radio.channel.list. See the connection example.
  4. Send WHO_AM_I and verify the expected authenticated user and connection-local state.
  5. In Radio, select Devices icon Devices, and find the expected device record. Confirm its intended user, advertising ID, display name, and current best-effort online state.

Troubleshooting

Use the following guidance if Oracle Radio mobile registration or sign-in fails.

The new QR value is rejected

Confirm that the intended Radio user is enabled and that the application supplies a nonempty advertising ID of no more than 255 characters. Create a new registration with a future expiration time, and scan only the newest QR value. Don't retry an expired, consumed, or revoked value.

Re-enrollment returns an unexpected device

Confirm whether the administrator re-registered the existing device record or created a registration for a new record. Store the device ID returned by the current completion response, and use that ID for heartbeats and the WebSocket upgrade.

The restored application remains offline

Completing re-enrollment closes existing WebSocket sessions for the replaced device registration. Confirm that the application uses a current bearer access token and the device ID returned by the completed re-enrollment. Send an authenticated heartbeat and include the same ID in the X-Oracle-Radio-Device-Id header during the WebSocket upgrade. After the connection opens, send the access token in AUTH and wait for AUTH_SUCCESS. Restore required live subscriptions and audio readiness; do not assume the old connection state survives.

For more failure guidance, see WebSocket help.

FAQ

Find answers to common questions about this Oracle Radio mobile workflow.

Does re-enrollment retain the prior Radio device ID?
Re-registering an existing Radio device record retains that record's device ID. Creating a registration for a new installation can return a new ID. Always store and use the device ID returned by the current registration completion.
Can the application reuse the earlier QR value?
No. A registration value is short-lived and can be used only once. Use the new QR value created for this re-enrollment.
Does the Radio device ID replace the bearer access token?
No. The ID identifies the registered application installation. The application must still send a valid Identity Domain bearer access token on every Radio REST request. For WebSocket, send the access token in AUTH when authenticating or renewing the session.

For more questions, see Radio Devices and Registration.