Introduction

Scenario: Your mission command app needs a risk view that filters disrupted, late, and exposed supply-chain entities and shows a few headline KPI tiles, driven directly against the Ontology over the REST API v2 from an OAuth2-authenticated client.

In this unit you stop relying solely on the generated OSDK helpers and drive the supply-chain Ontology directly over the Ontology REST API v2, the same HTTP surface the OSDK sits on top of. Your mission command app already renders object sets; now it needs an analyst-facing risk view that narrows the data and computes metrics on demand. You will use Search Objects to filter the Ontology server-side, and Aggregate Objects to compute count/sum/avg/min/max without pulling every row into the browser. Both are read-only operations, and both require the api:ontologies-read OAuth2 scope, so your client must be authorized correctly before a single request succeeds.

Because this app talks to Foundry as a third-party application, it authenticates with an OAuth2 client you configure in Developer Console. Foundry supports two grant types, and choosing correctly is the core judgment of this unit. The Authorization Code grant acts on behalf of the signed-in Foundry user via a browser redirect, issuing a short-lived access token (and, if you request the offline_access scope, a refresh token); it is the right choice for an interactive, governance-aware mission app because every request inherits the user's own permissions. The Client Credentials grant is non-interactive and runs as a Foundry service user, which is appropriate for unattended backends but wrong for a user-facing SPA. Scopes are space-delimited, and least-privilege matters: a read-only risk view should request only api:ontologies-read, with api:ontologies-write added solely where you later apply actions.

Be clear-eyed about what can and cannot be verified here. The OAuth2 client configuration, the chosen grant type, and the granted scopes live in your Developer Console application and in your client code; no documented Foundry READ API exposes them, so those steps are honestly self-attested. What is read-confirmable is the Ontology your app consumes: the same filter your Search view applies and the same metric your KPI tile displays can be reproduced server-side with an Aggregate Objects call, which is exactly how this unit's instance checks validate your work. You prove the risk view is faithful by reproducing its numbers against the Ontology, not by asserting the contents of your client bundle.

Capability focus: Ontology REST API v2 (Search Objects, Aggregate Objects); OAuth2 grant types; least-privilege token scoping. · Artifact: A risk view (or documented API call set) using Search + Aggregate over an OAuth2-authenticated client.

Key concepts

Companion video

1. 1

   Choose and register the OAuth2 grant type

   Register (or revisit) the OAuth2 client for this app in Developer Console and choose its grant type. For an interactive, user-facing mission command SPA, select the Authorization Code grant so the app acts on behalf of the signed-in Foundry user: a browser redirect obtains a short-lived access token, and requesting the offline_access scope yields a refresh token for longer sessions. Reserve the Client Credentials grant for non-interactive service workflows, since it runs as a Foundry service user rather than the operator, and set the client type (confidential vs public) to match how your SPA stores secrets. This step is self-attested: the OAuth2 client configuration and chosen grant type live in Developer Console and your client code, and no documented Foundry READ API exposes them, so record your choice and its rationale rather than expecting a check to read it back.

   not startedself-attested

   Mark complete

   Self-attested: the client is registered with the Authorization Code grant (acts on behalf of the signed-in user).

2. 2

   Filter the Ontology with Search Objects

   Build the risk view's filtered subset with Search Objects (POST /api/v2/ontologies/{ontology}/objects/Shipment/search), passing a query in the request body that selects shipments where status is 'late' and authenticating with the api:ontologies-read scope. The validation here does not assert your exact returned rows, because the platform's declarative check confirms a search-driven view through a count predicate rather than payload-matching; the instance check reproduces the same late-shipment subset using an Aggregate Objects count over Shipment where status='late' and confirms it matches the expected figure. Wire the search so its filter is identical to the aggregation's where clause, so the rows your analyst sees and the count the platform confirms describe the same slice of the Ontology.

   not startedinstance check

   Run check

   Confirms the late-shipment subset the search view targets reproduces via an aggregation.

3. 3

   Reproduce a headline metric with Aggregate Objects

   Compute the risk view's headline KPI tile with Aggregate Objects (POST /api/v2/ontologies/{ontology}/objects/InventoryItem/aggregate), a read-only call requiring api:ontologies-read, using a sum aggregation over the exposureUsd field. This computes total dollar exposure server-side instead of pulling every InventoryItem into the browser, which is both faster and aligned with least-privilege data movement. The instance check reproduces exactly this sum and confirms it equals the expected total exposure your KPI tile must display, proving the number the UI cites is reproducible against the live Ontology rather than computed from a stale or client-side copy.

   not startedinstance check

   Run check

   Confirms the app's KPI tile total exposure reproduces via a sum aggregation.

4. 4

   Verify least-privilege read scoping on the token

   Confirm least-privilege scoping on the client token: for these read flows the app should request only api:ontologies-read, with scopes space-delimited, and you should add api:ontologies-write only later when the app applies actions. Over-broad scopes are a real risk to a governance-aware mission app, so granting write access to a read-only risk view widens the blast radius for no benefit. This step is self-attested because the granted-scope state is configured in the OAuth2 client and is not readable through the data READ APIs; document which scopes the client requests and why each is necessary for the flows this unit implements.

   not startedself-attested

   Mark complete

   Self-attested: the client requests only api:ontologies-read for these read flows.