Product Lifecycle API Integration (Sample-to-Serial)
OAuth2 API Integration for a Product Lifecycle Gate (Sample to Serial)
A manufacturer's PIM platform gates every product's move from sample status to serial production status behind three checks: financial data completeness, a chosen color, a chosen size. I built and authenticated a Postman collection against the platform's identity server, using a cached OAuth2 password-grant token so a caller can run all three gate checks without re-authenticating on every request. The collection is scoped to what it actually proves: three verified gate calls, not the full multi-step flow the platform documents around them.
The problem
A manufacturer runs a product information management (PIM) platform that carries each product through its lifecycle, from an initial sample record to a production-ready serial record. That move is not automatic. Before a product can go to serial, three things have to be confirmed: the financial data (raw material, auxiliary material, and labour costs) is filled in, a color has been chosen, and a size has been chosen. Checking that by hand, per product, does not scale once more than a handful of items are moving through the pipeline at once. The platform exposes these three checks as an API, but the API sits behind an OAuth2 identity server, so any caller has to authenticate first, and do it without hitting that identity server on every single check it makes.
Constraints
- ·Resource-owner password grant only. The platform's identity server offered this grant type, not a client-credentials alternative, so the token request carries a username and password alongside the client id and secret.
- ·Read-only scope. The token is scoped to read access over the platform's product and API resources plus openid and offline_access, no write access requested.
- ·Three independent gate endpoints. Financial data, color, and size are separate calls, each needing the same bearer token.
- ·Test tier only, at build time. The environment available while building this was the platform's test tier. A production tier is reachable by swapping one Postman environment.
- ·No spec, only flow diagrams. The exported collection had no saved response examples and no test assertions, so the integration had to be verified against the platform's documented flow diagrams, not a written spec.
Architecture
A Postman collection authenticates against a PIM platform's identity server using a cached OAuth2 password-grant token, then calls three gate-check endpoints that decide whether a product record can move from sample to serial status.
- ›Postman collection defining 4 requests (token endpoint plus 3 gate checks)
- ›Prerequest script (JavaScript + moment.js) that checks and caches the bearer token
- ›OAuth2 identity server (/connect/token, resource-owner password grant)
- ›Three ProductLambda gate-check endpoints (financial data, color, size)
- ›Postman environment holding tier-specific URLs, scope, and credentials
How one request flows
- 01A caller triggers a request. The collection's prerequest script runs first, before any endpoint fires, regardless of which of the four requests was called.
- 02The script checks the cached token, reading tokenValidUntil from the environment and comparing it to the current time using moment.js.
- 03If the token is still valid, the script does nothing. The request proceeds straight to the endpoint, reusing the stored access_token through the collection's bearer auth.
- 04If the token is missing or expired, the script authenticates: it POSTs client_id, client_secret, grant_type=password, scope, username, and password to the token endpoint.
- 05The new token is cached: the response's access_token and computed expiry are written back into the environment, so the next call in this run, or the next run, reuses it without hitting the token endpoint again.
- 06The gate check runs. The caller hits one of check_financial_data, check_color, or check_size, each returning a yes/no verdict for that piece of the sample-to-serial decision.
- 07The verdict feeds the wider flow. Per the documented flow, a 'no' is meant to queue a missing-notification entry and show an error, a 'yes' carries the status forward toward the final sample-to-serial confirmation. Only the check call itself is confirmed built here.
Engineering decisions
Cache the token, don't refetch it every call
What. The prerequest script compares a stored expiry timestamp against the current time before deciding whether to re-authenticate.
Why. Three gate checks run back to back would otherwise pay a full OAuth round trip on each one for the same token.
Tradeoff. The alternative, authenticating on every request, is simpler to write but turns every batch of checks into a multiple of the real auth cost for no benefit.
Resource-owner password grant, not client-credentials
What. The token request carries a username and password alongside the client id and secret.
Why. That is the grant type the platform's identity server offers for this integration, not a client-credentials pair.
Tradeoff. This ties every automated call to one service account's password, so rotating that password means rotating it everywhere this integration runs. It was the grant available, not a choice made for convenience.
One check per concern, not one combined endpoint
What. Financial data, color, and size are three separate calls rather than one bundled 'validate product' request.
Why. Each maps to one yes/no gate in the documented flow, with its own missing-notification message, so a failure can point at exactly what is missing instead of returning one combined pass or fail.
Tradeoff. The cost is three round trips instead of one, which is a fair trade for a specific failure reason on each check.
Auth wired once, at the collection level
What. The bearer token is set as the collection's shared auth object, and environment variables carry every tier-specific value (base API URL, token URL, credentials).
Why. Moving from the test tier to a production tier is then a matter of swapping one Postman environment, not editing four requests by hand.
Tradeoff. Every request depends on one shared auth config, which is the right shape for a collection this size but would need per-request overrides if a future endpoint needed a different grant.
Scoped the claim to what the collection proves
What. The delivered integration is described as three gate checks (financial data, color, size) plus the auth that reaches them.
Why. The platform's flow documentation covers seven steps (financial data, color, size, showroom confirmation, a missing-notification list, sample/serial status, and a final notification send), but only three of those had a matching endpoint in the exported collection.
What changed along the way
- →Started by assuming each of the seven documented flow steps would have a matching API call. Tracing the collection showed only three had one, so the delivered scope was narrowed to what the collection actually calls.
- →Verified the token cache by reading a stored environment timestamp rather than trusting a simple valid/invalid flag, since Postman environments don't have native token-expiry handling built in.
- →Confirmed the three checks against the flow diagrams node by node, since the exported collection had no saved response examples to check the mapping against directly.
Security and reliability
- ·Scoped token: the OAuth2 grant requests read-only scope over the platform's product and API resources plus openid and offline_access, no write access.
- ·Cached, not repeated: the token is fetched once per expiry window and held only in the Postman environment, not re-sent as a fresh login on every call.
- ·Credentials out of the checked-in file: the client secret and service-account password are held as placeholders in the tracked environment file, with real values kept in a separate, git-ignored config.
- ·No retry or monitoring layer: this is a Postman collection run on demand, not a deployed service, so retries and alerting are the responsibility of whatever calls it, not the collection itself.
Metrics
What shipped
- ✓A working Postman collection that authenticates against the PIM platform's identity server and calls the three sample-to-serial gating checks (financial data, color, size) with a single shared, expiry-aware token flow.
- ✓A documented mapping between the API's ProductLambda checks and the broader sample-to-serial decision flow (color, size, financial data form, showroom confirmation, sample/serial status confirmation).
- ✓Environment-scoped configuration means the same collection reaches a production tier by swapping one Postman environment, no request-level edits.
Lessons learned
- ·Caching a token against a stored expiry is worth the extra state even in a tool as simple as a Postman environment, since naive per-call auth is the first thing to break under any real volume.
- ·A resource-owner password grant is a real constraint, not a style choice, when the identity server offers nothing else. Design around what the token can actually do.
- ·Flow diagrams and an API surface do not have to fully overlap. Scoping the integration to the checks it actually calls, instead of every documented step, kept the delivered claim honest.
- ·Empty response arrays and an empty test script in an exported collection are a signal to slow down and verify by hand, not a gap to assume away.