Brian Makarewicz
← Back to all posts

Oracle's BOSS REST APIs: The New Business-Object Layer Over FSCM and HCM

9 min readIntegration
oraclefusionrestbossapiintegration

Oracle's BOSS REST APIs: The New Business-Object Layer Over FSCM and HCM

If you have integrated with Oracle Fusion for any length of time, you know the two front doors. Financials and supply chain live under /fscmRestApi/resources. Human capital lives under /hcmRestApi/resources. Sales and service have their own under /crmRestApi. Each pillar shipped its own REST surface, each with its own versioning, its own quirks, and its own catalog of a few thousand resources.

Oracle is now shipping a second surface that cuts across all of them. You will see it in the documentation and in the wild as BOSS -- the path prefix is /api/boss, and Oracle's APEX integration guide expands the name as Business Object Spectra Services. Oracle APEX 24.2 added a first-class REST source type for it, which is usually the first sign that a Fusion feature is real and not a preview.

I spent a session pointing both the old APIs and the new BOSS endpoints at a live Fusion demo pod to see what actually changed. The query model is more capable. The authentication model is completely different, and that difference is not optional -- a BOSS call that works perfectly as a classic REST call will fail flat until you change how you authenticate. That is the part worth reading closely.

Throughout this post I have replaced the real pod hostname with <your-pod>. Everything else is verbatim from live calls.

The world you already know

The classic pillar APIs take Basic authentication and a query string. Here is a supplier lookup against Payables, filtered with the q parameter and trimmed to a few fields:

curl -u '<user>:<password>' \
  "https://<your-pod>/fscmRestApi/resources/11.13.18.05/suppliers?q=Supplier LIKE 'A%'&limit=3&onlyData=true&fields=SupplierId,Supplier,SupplierNumber" \
  -H "Accept: application/json"

That returns exactly what you would expect:

{
  "items" : [ {
    "SupplierId" : 300000047572113,
    "Supplier" : "Allied Manufacturing",
    "SupplierNumber" : "1265"
  }, {
    "SupplierId" : 300000047507272,
    "Supplier" : "American Telephone and Telegraph",
    "SupplierNumber" : "1259"
  }, {
    "SupplierId" : 300000075039541,
    "Supplier" : "ABC Consulting",
    "SupplierNumber" : "1288"
  } ],
  "count" : 3,
  "hasMore" : true,
  "limit" : 3,
  "offset" : 0
}

Invoices behave the same way. Same host, same Basic auth, same query grammar:

curl -u '<user>:<password>' \
  "https://<your-pod>/fscmRestApi/resources/11.13.18.05/invoices?limit=2&onlyData=true&fields=InvoiceId,InvoiceNumber,InvoiceAmount,InvoiceCurrency,Supplier"

{
  "items" : [
    { "InvoiceId": 45, "InvoiceNumber": "JGA  2012155", "InvoiceAmount": 98346.33, "InvoiceCurrency": "USD", "Supplier": "JGA" },
    { "InvoiceId": 46, "InvoiceNumber": "JGA  2012163", "InvoiceAmount": 118014.72, "InvoiceCurrency": "USD", "Supplier": "JGA" }
  ],
  "count": 2,
  "hasMore": true
}

This is the model most integrations are built on. It works, it is well understood, and Oracle is not taking it away. Hold onto how simple the auth was here, because it is about to change.

The new door: /api/boss

The BOSS endpoints live under a different path and read differently. Instead of a resource name plus a query string, you address a fully-qualified business object inside a module namespace, and you query it by POSTing a JSON body to a $query action.

The shape looks like this:

POST https://<your-pod>/api/boss/data/objects/ora/<module>/<domain>/v1/<object>/$query

A concrete one from Oracle's own documentation, for the tags object in the service-core module:

POST /api/boss/data/objects/ora/cxServiceCore/common/v1/tags/$query

The query is no longer a URL parameter. It is a structured JSON document:

{
  "collection": {
    "filter": "value LIKE 'Priority%'",
    "limit": 25,
    "offset": 0,
    "sortBy": [ { "value": "asc" } ],
    "privilege": "..."
  },
  "fields": [ "id", "value", "createdBy", "timeCreated" ],
  "parameters": {}
}

And the response is a clean, paginated envelope:

{
  "hasMore": false,
  "items": [
    {
      "id": "300000012345678",
      "value": "Priority-1",
      "createdBy": "SALESADMIN",
      "timeCreated": "2026-03-04T12:41:09+00:00",
      "$id": "...",
      "$context": { "etag": "...", "links": { "$self": { "href": "..." } } }
    }
  ]
}

A few things are genuinely nicer than the classic APIs. The filter, the field projection, sorting, and paging are all in one place instead of smeared across query-string parameters. The $query action is a POST, so a long or complex filter never runs into URL-length limits or encoding headaches. And the object model is explicit about composition -- child collections, search views, and extraction views are all first-class, rather than the expand-and-hope approach of the older resources.

How the namespace actually resolves

The URL segments are not decorative. Fusion collapses ora/cxServiceCore/common into a single module identifier, oraCxServiceCoreCommon, and it will tell you so when you get it wrong. I confirmed the mapping the direct way -- by getting it wrong on purpose against the live pod:

GET /api/boss/data/objects/ora
-> 404  {"title":"Module 'ora' not found."}

GET /api/boss/data/objects/ora/cxServiceCore/common/v1/tags
-> 401  {"title":"Anonymous access is not allowed for module: oraCxServiceCoreCommon"}

That second response is the whole story of this post in one line, so let us talk about it.

The part that will cost you an afternoon

On the classic APIs, I authenticated with curl -u user:password and got data back. When I sent the exact same Basic credentials to a BOSS endpoint, I got this:

curl -u '<user>:<password>' -X POST \
  "https://<your-pod>/api/boss/data/objects/ora/cxServiceCore/common/v1/tags/\$query" \
  -H "Content-Type: application/json" -d '{"collection":{"limit":2}}'
-> HTTP 401

No data, no WWW-Authenticate challenge, nothing. BOSS does not accept Basic authentication at all.

My next instinct was the one everyone has: log in through a browser, grab the session, and reuse it. So I logged into the pod with a real Chromium session, confirmed the login landed on the Fusion home page, and replayed the request with the live session cookie attached. BOSS answered:

{"title":"Anonymous access is not allowed for module: oraCxServiceCoreCommon"}

Read that carefully. The request carried a valid, freshly-minted Fusion login cookie, and BOSS still considered it anonymous. The single-sign-on cookie that authorizes every ADF page and every classic REST call means nothing to the BOSS layer. BOSS is served by a different runtime, and it authenticates one way only: an OAuth 2.0 Bearer token, a JWT, in the Authorization header.

This is the real difference between the two surfaces. It is not the URL shape or the JSON query -- those you would figure out from any example in five minutes. It is that your existing Basic-auth or cookie-based integration code cannot call BOSS by swapping the URL. You have to bolt on a token flow first.

Getting the token

There are two supported ways to get the JWT that BOSS wants, and which one you reach for depends on whether a human is present.

Token Relay, for browser and single-sign-on contexts. Fusion exposes a relay endpoint that hands a signed-in user a JWT:

GET https://<your-pod>/fscmRestApi/tokenrelay

Hit from a browser that already has a Fusion session, it returns JSON with access_token, principal, token_type, and expires_in. This is what tools like APEX use behind the scenes when you configure a BOSS REST source. One caveat from the field: token relay is a per-pod configuration, and it is not guaranteed to be enabled. On the demo pod I tested, the relay endpoint returned 401 even for a fully authenticated session, which means the only path left there is the OAuth flow below. Check your own pod before you design around it.

OAuth 2.0 against the identity domain, for server-to-server integrations. This is the durable answer for headless code. You register an OAuth client in the Fusion identity domain (Security Console, under API Authentication, or directly in the IDCS/IAM admin console), grant it the Fusion resource scope, and exchange client credentials for a token:

curl -u '<client_id>:<client_secret>' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -X POST "https://<identity-domain>/oauth2/v1/token" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:fusion:<pod>:boss/"

That returns the JWT. From there, BOSS behaves:

curl -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -X POST "https://<your-pod>/api/boss/data/objects/ora/cxServiceCore/common/v1/tags/\$query" \
  -d '{"collection":{"limit":2}}'

One practical warning I ran into. You cannot borrow the identity domain's built-in Fusion application client for an ad-hoc flow -- it only accepts its own registered redirect URIs, and every attempt to use it with a different redirect or a client-credentials grant is refused with invalid_redirect_uri or invalid_request. You have to register your own client. That is a deliberate, standard security-console step, but it is a step, and it is the reason a BOSS integration takes longer to stand up than a classic REST one even though the queries are simpler.

Discovering what is actually there

The classic APIs have a describe endpoint that dumps every resource. BOSS has an OpenAPI surface instead:

GET https://<your-pod>/api/boss/data/openapi

That endpoint is live -- it returns an OpenAPI document rather than a 404 -- and it is how tooling like Oracle's AI Agent Studio Business Object tool learns the object catalog. Point it at a module and it will give you the objects, their fields, their filterable and sortable attributes, and the $query contract for each. This is the right place to start on your own pod, because the set of BOSS-enabled modules is still growing release over release, and it differs by what you have provisioned.

So does BOSS replace FSCM and HCM?

Here is the honest read, and it is more nuanced than the headline.

BOSS is the direction Oracle is moving. It is the query layer underneath the Redwood user experience, it is what the new AI agent tooling calls, and it is a cleaner model than the pillar-specific resources it sits beside. If you are starting an integration today against objects that expose a BOSS view, it is worth building on.

But "replace" is too strong for right now. The classic /fscmRestApi and /hcmRestApi resources still cover business objects that have no BOSS equivalent yet -- large parts of Payables, Receivables, Assets, and General Ledger among them. The two surfaces coexist, and they will keep coexisting for a good while. The migration is happening object by object, not with a switch that flips the whole platform over.

The practical guidance I would give a team:

  • If you already have a working classic REST integration, do not rip it out. It is not deprecated, and nothing you built stopped working.
  • For new work, check the BOSS OpenAPI on your pod first. If the object you need is there, the query model is better and it is the more future-proof choice.
  • Budget for the authentication difference on day one. Every BOSS integration needs a registered OAuth client and a token flow. Do that setup before you write a single query, because you cannot test anything until it is in place.
  • If your context is a signed-in user rather than a server -- an APEX app, a Redwood extension -- lean on token relay where it is enabled, and confirm it is enabled early.

The queries are the easy part. The token is the whole game. Get that sorted and BOSS is a genuinely nicer way to talk to Fusion.