Oracle Update Advisor API Reference and Integration Guide

What is Oracle Update Advisor?

Oracle Update Advisor (OUA) is a REST service that evaluates Oracle software configurations, reports software health, and provides software recommendations aligned with Oracle update policies. This reference is for developers who want to integrate directly with OUA outside native Oracle tools such as Database Configuration Assistant (DBCA), Fleet Patching and Provisioning (FPP), and AutoUpgrade.

OUA is a secured service. Only registered Oracle customers can call the health and recommendation endpoints. A client must first complete a one-time registration to obtain an API key. After registration succeeds, the client reuses the same API key, together with the corresponding RSA private key, to authenticate and sign subsequent Oracle Update Advisor API requests. Oracle SSO credentials are used only during registration and are not required for runtime health or recommendation API calls.

Typical OUA workflow:

1. Register to obtain an API key.
2. Call the Health API to evaluate software health.
3. If the returned status is not GREEN, call the Recommendation API.
4. If requested and available, use the returned image metadata for gold image workflows.

Base URLs and Authentication

The service endpoint is:

https://updateadvisor.oracle.com/

This endpoint is the canonical endpoint for production workloads.

All operation paths in this document are relative to this base URL. For example:

• Registration: POST /v2/patchplanner/registration
• Health request: POST /v2/patchplanner/requests
• Async polling: GET /v2/patchplanner/requests/{requestId}

Customer Authentication Model

Oracle Update Advisor uses the following authentication model for customers:

1. The client generates an RSA key pair locally.

2. The client calls the registration API using:

   • Oracle SSO username and password
   • Base64-encoded public key
   • Tool name
3. The service returns an API key.
4. All subsequent protected API requests:
   • Use the issued API key
   • Are signed with the client’s corresponding private key
   • Do not require Oracle SSO credentials again

Oracle SSO credentials are used only during registration. After registration succeeds, the API key and request signature are the only runtime authentication mechanism for Oracle Update Advisor API requests. Do not send Oracle SSO credentials with health, recommendation, polling, or DELETE requests.

Authentication and Signing Workflow

Registration is a one-time setup step. A client generates an RSA key pair, registers the public key with Oracle Update Advisor, receives an API key, and then reuses that API key for subsequent Oracle Update Advisor API requests.

Each protected request must be signed with the RSA private key that corresponds to the public key submitted during registration.

1. Generate an RSA key pair for the client application.
2. Store the private key securely in the client environment. The private key must never be sent to Oracle Update Advisor.
3. Call the registration API to obtain an API key.
4. Persist the API key, private key, and configuration metadata in a secure local location, such as ~/.<toolName>/.
5. For each runtime API request, compute a millisecond Unix timestamp.
6. Build the canonical string as METHOD|API_KEY|TIMESTAMP|PAYLOAD.
7. Sign the canonical string with RSA PKCS#1 v1.5 using SHA-512.
8. Base64-encode the signature without line breaks.
9. Send the API key and signature in the Authorization header using the oracle-dts-signed scheme.
10. Reuse the same timestamp value in the date header.

Authorization Header and Message Signing

Update Advisor uses a custom signed-request authorization scheme rather than OAuth, IDCS token exchange, or a conventional bearer token. Every protected request must include a digitally signed Authorization header that proves possession of the API key and corresponding RSA private key. The server validates the signature, timestamp, and payload hash to block tampering or replayed traffic.

Header format notes:

Build the canonical string as METHOD|API_KEY|TIMESTAMP|PAYLOAD, where PAYLOAD is the exact byte sequence sent in the body. For bodyless GET and DELETE requests, use an empty payload string. Sign this string with RSA PKCS#1 v1.5 using SHA-512, and then Base64-encode the signature. Any change to the method, API key, timestamp, or serialized payload invalidates the signature.

1. Generate a millisecond timestamp: timestamp_ms = time.time_ns() // 1_000_000.

2. Serialize the request payload exactly once and preserve that exact byte sequence for both signing and transmission. For bodyless GET requests, use an empty payload string.

3. Construct the canonical string as METHOD|API_KEY|TIMESTAMP|PAYLOAD.

4. Sign canonical with RSA SHA-512 using the registered private key. Remove any line breaks from the Base64 output.

5. Set the headers to Authorization: oracle-dts-signed {api_key} {signature} and date: {timestamp_ms}.

6. Send the payload byte-for-byte as signed.

Example canonical string for POST:

POST|{apiKey}|{timestamp_ms}|{"requestType":"SoftwareGetStatus","locale":{"langCode":"en","countryCode":"US"}}

HTTP/1.1 request example:

POST /v2/patchplanner/requests HTTP/1.1
Host: updateadvisor.oracle.com
Content-Type: application/json
Accept: application/json
Authorization: oracle-dts-signed {apiKey} {signature}
date: {timestamp_ms}

Example canonical string for asynchronous GET polling:

GET|{apiKey}|{timestamp_ms}|

For asynchronous polling requests, the payload is empty. The trailing separator (|) must still be included in the canonical string.

Re-register only for UPD-02002 or a confirmed invalid/expired API key. Otherwise, first validate the timestamp, header, payload, and signature. Treat private keys as secrets: store them outside source control, encrypt them at rest, and rotate them in concert with API key regeneration.

Credential Lifecycle

The API key returned by the registration API is the persistent credential used for subsequent Oracle Update Advisor API requests.

• API key validity: API keys are valid for 365 days.
• Rotation: To rotate credentials, generate a new RSA key pair and call the registration API again to obtain a new API key.
• Expiration: If an API key expires, the service returns UPD-02002. The client must re-register before sending additional protected API requests.
• Expiration warning: The service may return UPD-01501 when the API key or public key is nearing expiration.
• Multiple active API keys may exist for a registered user.
• Revocation: Use DELETE /v2/patchplanner/registration with a signed request to revoke an API key.

Clients should monitor service message codes in every response and re-register before credentials expire.

Security Considerations

All registration and API requests must be sent over HTTPS using TLS 1.2 or later.

During registration, the client sends Oracle SSO credentials only to authenticate the user and issue an API key. SSO credentials are not used for runtime API calls and must not be persisted by the client after registration.

The API key is the persistent credential returned by the service. Store it securely with the client configuration.

The RSA private key must remain in the client environment and must never be sent to Oracle Update Advisor. Only the Base64-encoded public key is sent during registration. All protected requests are signed locally using the private key.

Oracle Update Advisor does not store the Oracle SSO password beyond the registration authentication transaction.

API Summary

Use the POST variant to submit a request. If the service returns 202 Accepted, poll the returned request ID using the GET form of the same endpoint.

API Operations

Use the following information to carry out API operations.

Registration API

The Registration API establishes the credentials required to access Oracle Update Advisor. Clients register their public key and receive an API key used to authenticate and sign subsequent OUA requests. The API also supports verifying and revoking an existing registration.

Register client

POST /v2/patchplanner/registration
Content-Type: application/json
Accept: application/json

Request fields

Example request

{
 "username": "user@example.com",
 "password": "<password>",
 "publicKey": "<public-key-base64>",
 "toolName": "Automation"
}

Example response

{
 "apiKey": "<issued-api-key>"
}

Verify registration

GET /v2/patchplanner/registration
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>

Optional locale headers:

• x-lang-code defaults to en.
• x-country-code defaults to US.

Revoke registration

DELETE /v2/patchplanner/registration
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>

Software Health Status and Recommendation API

The Health Status and Recommendation API evaluates installed Oracle software against the update policy supplied in the request. Both supported operations use the same endpoint and a largely shared request structure. The requestType field determines whether the service returns a health assessment only or a health assessment together with detailed recommendations.

Both runtime request types use:

POST /v2/patchplanner/requests

The requestType discriminator selects the operation:

Required headers

Top-level request fields

System information

globalElement.systemInfo is required. A request element can supply systemInfo to override the global values.

Policy parameters

globalElement.policy is required. A request element can supply policy to override individual global values. Missing request-element values inherit from the global policy and then from server rules.

applyFrequency values

recommendationArea values

recommendationArea is a comma-separated string. It can contain functional recommendation-area directives and zero or one security-level directive.

Functional recommendation-area directives:

Security-level directives:

The Common Vulnerability Scoring System (CVSS) is a standardized 0.0–10.0 vulnerability-severity scale.

Security levels are values of recommendationArea; the request schema does not define a separate securityLevel field.

Security health assessment cannot be disabled. If no security-level value is supplied, the service applies SecurityHigh to the effective policy.

Valid examples:

SecurityHigh
IncludeNonRolling,SecurityMedium
IncludeNonRolling,JDK,SecurityHigh
ALL,SecurityCritical

Validation rules implemented by the service:

• Values are matched case-insensitively.
• Comma-separated values are trimmed.
• At most one security-level value can be supplied.
• Repeating the same security-level value is rejected as multiple security directives.
• An unknown value beginning with Security returns validation error 04049.
• Multiple security-level values return validation error 04048.
• If no security-level value is supplied, the effective policy uses SecurityHigh.

Request-element fields

goldImage is a string enum in the current schema, not a JSON boolean.

SoftwareGetStatus example

{
  "requestType": "SoftwareGetStatus",
  "locale": {
    "langCode": "en",
    "countryCode": "US"
  },
  "globalElement": {
    "systemInfo": {
      "platform": "226",
      "cluster": "true"
    },
    "policy": {
      "updateLag": "N",
      "applyFrequency": "Q",
      "notificationLevel": "Critical"
    }
  },
  "requestElement": [
    {
      "id": "1",
      "policy": {
        "updateLag": "N",
        "applyFrequency": "Q",
        "notificationLevel": "Critical",
        "recommendationArea": "SecurityHigh"
      },
      "installedSoftwareInfo": {
        "version": "19.28.0.0.0",
        "type": "DB"
      },
      "patchList": {
        "installedPatches": [
          {
            "number": "11111",
            "upi": "111111"
          }
        ],
        "additionalRequestedPatches": [
          {
            "number": "22222",
            "upi": "222222"
          }
        ]
      }
    }
  ]
}

SoftwareGetStatusAndRecommendation example

{
  "requestType": "SoftwareGetStatusAndRecommendation",
  "locale": {
    "langCode": "en",
    "countryCode": "US"
  },
  "globalElement": {
    "systemInfo": {
      "platform": "226",
      "cluster": "true"
    },
    "policy": {
      "updateLag": "N",
      "applyFrequency": "Q",
      "notificationLevel": "Critical"
    }
  },
  "requestElement": [
    {
      "id": "1",
      "policy": {
        "updateLag": "N",
        "applyFrequency": "Q",
        "notificationLevel": "Critical",
        "recommendationArea": "IncludeNonRolling,SecurityMedium"
      },
      "installedSoftwareInfo": {
        "version": "19.28.0.0.0",
        "type": "DB"
      },
      "patchList": {
        "installedPatches": [
          {
            "number": "11111",
            "upi": "111111"
          }
        ],
        "additionalRequestedPatches": [
          {
            "number": "22222",
            "upi": "222222"
          }
        ]
      },
      "goldImage": "true"
    }
  ]
}

Polling API

Retrieves the status or completed result of a previously submitted asynchronous health or recommendation request. Use the requestId returned with the original 202 Accepted response to poll until processing completes.

GET /v2/patchplanner/requests/{requestId}
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>

Use an empty payload in the canonical signing string for polling requests.

Lookup API

Retrieves lookup data used to plan RAC two-stage rolling updates. The response is selected using parameters such as category, Oracle Database version, and platform.

GET /v2/patchplanner/lookup
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>
Accept: application/json

The Lookup API requires a signed request. Because the GET request has no body, use an empty payload when constructing the canonical signing string:

GET|{apiKey}|{timestamp_ms}|

Query parameters

Example:

GET /v2/patchplanner/lookup?category=ractwostagerollingupdates&version=23&platform=226
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>
Accept: application/json

Responses

Runtime request responses can include:

• serviceMessages — messages applying to the overall response.
• requestType — submitted request type.
• referenceId — request correlation identifier.
• requestStatus — request-level status and messages.
• globalElement — effective global system information and policy.
• responseElement — per-element health, recommendation, status, and timing data.

requestStatus.value values:

• Pending
• Completed
• InvalidRequest
• Rejected

responseElement.status.value values:

• Success
• Pending
• InvalidRequest
• Failed

A runtime request can return HTTP 200 with an element-level InvalidRequest. Clients must inspect requestStatus, serviceMessages, and each responseElement.status.

Status Codes

When retrieving asynchronous results, reuse the same Authorization signature pattern and include an empty payload in the canonical string for GET requests.

Request Lifecycle and Throttling

Oracle Update Advisor processes lightweight evaluations synchronously. Larger inventories or recommendation requests may be accepted for asynchronous processing, returning HTTP 202 Accepted with a request ID and polling URI. Retrieve the result by sending a signed GET request to the polling URI. Generate a new timestamp and signature for each polling request, and use an empty payload in the canonical signing string. The service enforces rate limits per API key. If the service returns HTTP 429 Too Many Requests, reduce the request rate and retry using exponential backoff. Monitor UPD-02001 service message for throttling feedback.

Clients should also monitor credential lifecycle messages. UPD-01501 indicates that an API key or public key is nearing expiration. UPD-02002 indicates that the API key has expired and the client must re-register before continuing.

Service Message Codes

Client handling rules:

• If the service returns 200 OK, process the response immediately.
• If the service returns 202 Accepted, extract the returned request identifier or polling URI and continue polling with signed GET requests.
• For signed polling GET requests, use an empty payload in the canonical signing string.

Additional Information

Use these guidelines to assist you with update analysis.

Minimal Client Flow

A minimal Oracle Update Advisor client performs the following steps:

1. Generate an RSA key pair locally.
2. Register once with Oracle SSO credentials, the generated Base64-encoded public key, and a tool name.
3. Persist the returned API key securely with the private key and local client configuration.
4. Build a signed POST request to /v2/patchplanner/requests with request type SoftwareGetStatus.
5. Send the runtime request using the API key and signature. Do not send Oracle SSO credentials.
6. If the service returns 200 OK, read the health status from the response.
7. If the service returns 202 Accepted, poll /v2/patchplanner/requests/{requestId} using signed GET requests until the final response is returned.
8. If the resulting health status is not GREEN, submit a signed SoftwareGetStatusAndRecommendation request.

Best Practices

• Persist keys and configuration under a restricted directory such as ~/.<toolName>/ with 600 permissions.
• Serialize the payload once and reuse the same byte stream for signing and transmission to avoid signature mismatches.
• Use millisecond-resolution timestamps and reject stale signatures to protect against replay attacks.
• Batch multiple assets in a single requestElement array when feasible to minimize API calls.
• Monitor service messages in every response to capture expiring credentials, throttling feedback, or policy issues.
• Log referenceId and requestID values for traceability when engaging Oracle Support.
• Do not persist Oracle SSO passwords after registration.
• Do not send Oracle SSO credentials with health, recommendation, polling, or DELETE requests.
• Re-register before API key expiration when the service returns UPD-01501.