Oracle Cloud Infrastructure Documentation

Authenticating with Oracle Radio APIs

Start with the client you use, prepare its access, and verify authentication before sending Radio requests.

Public health and ping diagnostics require no authentication. Use the steps below for protected Radio operations.

Use a browser session to work in the Radio web application. Use Identity Domain bearer access tokens when the supported Radio mobile application calls APIs outside that browser session. REST and WebSocket don't require different sign-in methods; they carry the authenticated client's credentials differently. This summarizes the authentication overview.

If you need to create or manage a Public Safety and Security instance rather than use Radio, follow Public Safety and Security setup. Those OCI resource operations use OCI authentication and IAM policies.

Start with Your Client

Use the following table to find the supported authentication path for your client and task.

Your taskWhy this method appliesStart here
Use Radio in a web browser.The Radio web application manages the signed-in browser session and request protection for you. You don't obtain or copy an access token.Browser steps
Enroll and use the supported Radio mobile application.The installed application needs user credentials for its own REST requests and WebSocket connection. It uses the public OAuth client managed by Public Safety and Security with Authorization Code and S256 PKCE, without a client secret.Mobile steps
Use a command-line, custom-browser, or server client.These authentication contracts are not currently supported. Bearer authentication is supported for Radio mobile clients, not a general-purpose client login workflow.Use the supplied Radio browser or mobile application. Do not create a customer OAuth application or reuse mobile credentials as a workaround.

Before You Begin

  1. Get the instance details or ask your administrator for its endpoints. Confirm that the Public Safety and Security instance is ACTIVE. Use uiEndpoint for the web application and serviceEndpoint for REST requests.
  2. Have an administrator verify your active account in the instance's Identity Domain and enable access for the corresponding Radio user.
  3. Have a Radio administrator assign the Radio permissions and any channel access needed for your task. Signing in alone doesn't grant them.

Use Oracle Radio in a Browser

Follow these steps to operate Radio through its web application. The application handles the session and API authentication; you don't register a mobile device for this browser workflow.

  1. Open the instance's uiEndpoint. For help finding the Oracle Radio app endpoint on the Public Safety and Security instance details page, see Getting a Public Safety and Security Instance for more information.
  2. If prompted, sign in to the configured Identity Domain and allow the browser to return to Radio. If your session expires while you are using Radio, allow the application to return you to sign-in. Complete sign-in and verify your channel and connection before resuming work.
  3. Verify your displayed identity and available channels. Follow the sign in steps for details, or access guidance if sign-in succeeds but Radio denies access.
  4. Use the Radio controls for your task. When finished, sign out.

Don't copy session cookies or send a bearer AUTH message on the application's gateway-authenticated WebSocket connection. For request protection, see browser security.

Authenticate and Register the Oracle Radio Mobile Application

Use this sequence when enrolling the supported installed application. As an app user, follow mobile enrollment: scan the administrator-issued QR value and sign in as its intended user. The application performs the OAuth and API steps below.

  1. Have a Radio administrator create a one-time device registration for the intended enabled user. The administrator needs the enrollment permission; the Devices page also requires device management.
  2. Read the instance URL, Identity Domain URL, public client ID, and exact Radio scope from the registration value. Prepare Authorization Code with a new S256 PKCE challenge, state, and nonce. Use the installed application's supported callback, not a new callback or client secret. See the authorization request.
  3. Have the intended user sign in. Validate the returned state, exchange the code with the original PKCE verifier, and validate the ID token. Store the access and refresh tokens in platform-protected storage. Follow the token steps for scopes and validation details.
  4. Complete registration once with that user's access token, one-time grant, and the installation's advertising ID. Retain the returned Radio device ID. Use the registration example; don't submit a successfully consumed grant again.
  5. Verify access using the steps below. While the application is active, send authenticated device heartbeats and renew access through the supported token flow.

The sequence above uses a one-time grant. For multiple installations of the same user, see reusable registration; the user authentication requirements are unchanged.

Public Safety and Security maintains the mobile OAuth configuration. The QR value and device ID don't authenticate a user, and they aren't token-renewal credentials. If the installation has lost its device ID, follow mobile re-enrollment.

Recover a Mobile Sign-in Session

The Android and iOS applications use Authorization Code with PKCE and renew access automatically using a valid saved refresh token. An access token expiring doesn't by itself mean you must enroll the device again.

  1. If the app loses connectivity or temporarily can't renew access, restore the network connection and allow it to retry. Communication can remain unavailable until renewal succeeds.
  2. Both Android and iOS return to sign-in when saved refresh credentials are missing, expired, or definitively rejected. Sign in again as the intended user. Use the app's sign-in controls; don't extract or replace tokens manually.
  3. If the app remains unable to recover, contact your administrator with the app version, time, and nonsensitive error text. Don't include tokens or the enrollment QR value. See session help.

Use re-enrollment when registration or installation configuration must be restored, not as the first response to a network or token-refresh failure. Signing out of the app is separate from going off duty.

Verify a Bearer-Token Client's Access

After the supported client obtains a current access token, use REST to verify a request or WebSocket to establish a live session. Use both when your workflow needs saved state and live communication; these tabs aren't alternative ways to obtain a token.

The profile check and WebSocket authentication below require an enabled Radio user with radio.channel.list. Later operations can require additional permissions and channel access.

    1. Append v1/radio/me to the returned serviceEndpoint, which already includes /api/.
    2. Send a GET request with Authorization: Bearer followed by the current access token. Follow the request example for cURL and PowerShell.
    3. Confirm HTTP 200 and the expected radioUserId. Then send the token in the authorization header on each REST request. See the profile reference for response details.
    1. Construct the WebSocket URL from the instance endpoint. For the registered mobile installation, include its Radio device ID in X-Oracle-Radio-Device-Id during the upgrade.
    2. Open the connection, then send the access token in an AUTH message. An upgrade Authorization header doesn't authenticate this bearer-token path.
    3. Wait for AUTH_SUCCESS before sending Radio operations. Send WHO_AM_I and verify the user. Follow authentication help for AUTH_ERROR.
    4. When renewing an open bearer-token session, send AUTH with a fresh access token for the same user and wait for AUTH_SUCCESS. Follow the session lifecycle for expiry and reconnection.

How Authentication Protects Access

Browser sessions and validated Identity Domain access tokens establish the caller's identity. Radio separately checks whether the user is enabled and authorized for each operation. Identity Domain groups and Radio groups are separate. A valid sign-in doesn't bypass Radio permissions or channel access.

For the public mobile client, PKCE binds the authorization-code exchange to the application's sign-in attempt without a client secret. Never put access or refresh tokens in URLs. Keep tokens, authorization codes, PKCE verifiers, registration values, and authentication messages out of logs and support records. A talk token grants the talk floor only; it isn't a sign-in credential.

How Browser Requests Are Protected

The Radio web application uses the gateway-managed session and its CSRF value to protect against another site causing unintended requests. The application supplies the value on protected state-changing REST requests and as the lowercase x-csrf-token query parameter when opening its WebSocket connection. You don't enter this value manually when using the application.

The gateway CSRF behavior applies to the supplied browser application. There is no supported public CSRF acquisition or renewal procedure for a custom browser client.

The CSRF value doesn't replace the signed-in session and isn't an access token. Bearer-token clients don't use browser CSRF state. Don't copy browser-session data into another client.