Authenticating an Oracle Radio WebSocket Session

Send an AUTH message to authenticate or renew a bearer-token WebSocket session.

Permissions and Prerequisites

The following permissions and prerequisites apply to this operation.

Requirement	Value
Authentication path	Use `AUTH` only for a supported Radio mobile bearer-token client. A gateway-authenticated browser connection must not send this message. See authentication.
Radio permission	The bearer must resolve to an enabled Radio user with `radio.channel.list`. Other operations require their own permissions.
Channel access	No channel access or channel subscription is required to authenticate.
Session state	The WebSocket connection must be open. For renewal, the new token must represent the same principal as the current authenticated session.

Request

For a registered mobile installation, supply exactly one valid X-Oracle-Radio-Device-Id during the upgrade. A supplied malformed, repeated, or unknown device ID causes authentication to fail; it does not merely omit device tracking. The device ID is not a credential. After the WebSocket connection opens, send AUTH as a JSON text message. The upgrade Authorization header doesn't authenticate this bearer path.

Name	Data type	Required	Default	Constraints	Description
`type`	string	Yes	None	Must be `AUTH`.	Identifies the authentication operation.
`token`	string	Yes	None	Must contain a nonempty, current OCI Identity Domain access token.	Authenticates the bearer-token client. Protect this value as a credential; don't log or persist the message.

{
  "type": "AUTH",
  "token": "<access-token>"
}

Responses

The following table lists the messages the client can receive and explains their purpose.

Message type	Kind	Description
`AUTH_SUCCESS`	Direct response	Confirms initial authentication or successful renewal for the same principal.
`AUTH_ERROR`	Error	Indicates that authentication failed, the renewal represents a different principal, or the connection uses gateway-managed browser authentication. An unsuccessful renewal doesn't replace the currently accepted authentication state.

AUTH_SUCCESS Response

The following table describes the response properties, their data types, and whether they are required.

Name	Data type	Required	Description
`type`	string	Yes	Response type. The value is `AUTH_SUCCESS`.
`audioReadiness`	object	No	For a device-bound connection, contains positive integer `renewalIntervalSeconds` and `expirySeconds`. Use these values for audio readiness; they are not access-token or heartbeat intervals.

{
  "type": "AUTH_SUCCESS"
}

AUTH_ERROR Response