Oracle Cloud Infrastructure Documentation

Registration Grant REST Operations for Oracle Radio

Create, inspect, revoke, and reissue registration grants for Radio application installations.

An enabled Radio user needs radio.enrollment.manage for each operation on this page. Verify the administrator's permissions. Registration grants enroll an installation; they don't authenticate its user.

The paths below start at the managed instance origin. When using the returned serviceEndpoint, append only the portion after /api/. See the REST overview for endpoint, authentication, and request guidance.

List Eligible Users

Operation: listDeviceRegistrationUsers.

GET /api/v1/management/device-registration-users

Find enabled Radio users before creating or reissuing a registration.

ParameterLocationRequirement
limitQueryOptional integer from 1 through 100; default 50.
offsetQueryOptional nonnegative integer; default 0.

Success: 200 with users, count, limit, offset, and hasMore. Each user has radioUserId; displayName and email can be null.

For another page, increase offset by the returned count while hasMore is true. This operation doesn't enable an Identity Domain user or a Radio user.

Create a Registration

Operation: createDeviceRegistration.

POST /api/v1/management/device-registrations

Create a grant for new installations of the intended user. The default is one-time use. A reusable grant permits multiple completions until expiry or revocation, with a new device record for each completion. See reusable registration.

ParameterLocationRequirement
intendedRadioUserIdJSON bodyRequired nonempty Radio user identifier from listDeviceRegistrationUsers. Use the returned radioUserId.
displayNameJSON bodyRequired nonblank display name, up to 256 characters.
usageModeJSON bodyOptional ONE_TIME (default) or REUSABLE. Both remain bound to the intended Radio user.
expiresAtJSON bodyRequired future date and time with a timezone offset.

Replace the bracketed values with your values before sending this JSON request. Supply Content-Type: application/json.

{
  "intendedRadioUserId": "<radio-user-id>",
  "displayName": "<installation-name>",
  "expiresAt": "<future-date-time-with-offset>"
}

Success: 201 with registration, descriptor, and qrValue. The registration includes registrationId, intended user, display name, usageMode, expiration, and creation time.

Correct invalid request values before retrying. Verify the intended user's Radio access and the administrator's enrollment permission. Give the QR value only to the intended user. Don't log it or include it in support records.

List Registrations

Operation: listDeviceRegistrations.

GET /api/v1/management/device-registrations

Review one bounded page of current and terminal grants. No request body is required.

Query parameterRequirement
usageModeOptional ONE_TIME or REUSABLE. Omit to list both modes.
limitOptional integer from 1 through 100; default 50.
offsetOptional nonnegative integer; default 0.

Success: 200 with registrations, count, limit, offset, and hasMore. Grant fields include registrationId, intendedRadioUserId, displayName, usageMode, expiresAt, and createdAt; targetRadioDeviceId, consumedAt, and revokedAt can be null.

While hasMore is true, increase offset by the returned count and keep the same filter and limit. One response is not the entire registration inventory.

Use registrationId as grantId when revoking a grant. This list doesn't return the registration code or QR value. If the issued value is lost, create a new grant or reissue registration for the existing device.

Revoke a Registration

Operation: revokeDeviceRegistration.

DELETE /api/v1/management/device-registrations/{grantId}

Revoke an active registration grant. A reusable grant can be revoked after successful completions; a one-time grant is consumed by its first completion.

ParameterLocationRequirement
grantIdPathRequired registration identifier containing only ASCII letters, digits, underscores, and hyphens. Use the identifier returned by Radio.

Success: 204 with no response body.

Revocation prevents use of the registration grant. It doesn't delete an enrolled device. For inventory removal, use Delete a Device.

Reissue Registration

Operation: reissueDeviceRegistration.

POST /api/v1/management/devices/{deviceId}/registration

Issue a targeted one-time registration for an existing device record, retaining its Radio device ID. Reissue does not accept a reusable usage mode.

ParameterLocationRequirement
deviceIdPathRequired radioDeviceId from a device response; 1–32 characters. Encode it as one URL path segment.
intendedRadioUserIdJSON bodyRequired nonempty Radio user identifier from listDeviceRegistrationUsers. Use the returned radioUserId.
expiresAtJSON bodyRequired future date and time with a timezone offset.

Replace the bracketed values with your values before sending this JSON request. Supply Content-Type: application/json.

{
  "intendedRadioUserId": "<radio-user-id>",
  "expiresAt": "<future-date-time-with-offset>"
}

Success: 201 with registration, descriptor, and qrValue. The grant's targetRadioDeviceId identifies the existing installation record.

Correct invalid request values before retrying. Verify the intended user's Radio access and the administrator's enrollment permission. Complete the new grant through mobile registration. Reissuing the grant alone doesn't complete enrollment.

Use the Returned Registration Values

Create and reissue return three values with different purposes:

ValueUse
registrationGrant metadata, including registrationId, the intended Radio user, display name, and expiration. Use the registration ID for revocation.
descriptorVersioned application-registration data: version, radioBaseUrl, identityDomainUrl, mobileClientId, authorizationScope, registrationId, code, displayName, and expiresAt. Follow the supported mobile flow and use the returned scope exactly.
qrValueThe JSON-encoded descriptor used for QR rendering. Deliver it securely to the intended user.

The descriptor is unsigned and contains a registration code. Its version 1 format is the same for both grant modes and does not include usageMode; read the mode from the separate registration metadata. It doesn't contain a client secret, OAuth token, or application callback URI. Follow the enrollment scenario for sign-in and completion.