DEV Community

Mostafa Mansour
Mostafa Mansour

Posted on • Originally published at opalapi.dev

"Oracle Fusion REST API Authentication: Basic Auth vs JWT vs OAuth 2.0"

#oracle #api #security #tutorial

Every Oracle Fusion REST API call — HCM, Financials, or SCM — starts with the same question: how do I authenticate? Oracle supports three mechanisms, and picking the wrong one for your scenario is the most common reason integrations stall in week one.

Here's the short version of each, when to use it, and the 401-vs-403 distinction that resolves most "authentication" tickets.

One rule first

Fusion authorization is always user-based. Whatever method you choose, the token or credential resolves to a Fusion user, and that user's roles decide what the request can touch. There is no app-only access to business data — server-to-server flows run as a dedicated integration user.

Option 1: Basic Auth over TLS

Zero setup. Credentials travel base64-encoded in the Authorization header on every request.

curl -u 'integration.user@example.com:YourPassword' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?limit=5'
Enter fullscreen mode Exit fullscreen mode

Fine for development and quick internal scripts. Not great long-term: passwords expire on the pod's rotation policy (integrations break silently at 3 a.m.), and the header is the full identity — replayable if leaked.

Option 2: JWT bearer with a trusted issuer

The middle path. Your system signs a JWT with a private key; Fusion validates it against a certificate you uploaded once (Security Console → API Authentication). No identity-domain round trip per request, no password rotation problem.

{
  "iss": "www.example.com",
  "prn": "integration.user@example.com",
  "sub": "integration.user@example.com",
  "iat": 1780000000,
  "exp": 1780000900
}
Enter fullscreen mode Exit fullscreen mode

Sign with RS256, send as Authorization: Bearer <jwt>. The prn/sub claim must match an active Fusion username — that user's roles are what the request runs with. Keep exp short; the token is self-contained, so a leaked one is valid until expiry.

Option 3: OAuth 2.0 via IDCS / IAM

The production-grade option, and required when a third party or federation (Entra ID, Okta) is involved. Register a confidential application in the identity domain linked to your Fusion instance, enable the grants you need, add the Fusion resource scope.

Because Fusion needs a user context, pure client-credentials tokens are not enough for business-object APIs — server-to-server flows use the user assertion variant: your app authenticates with its client credentials and asserts which Fusion user the token represents.

curl -u '<client_id>:<client_secret>' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
  --data-urlencode 'assertion=<signed user-assertion JWT>' \
  --data-urlencode 'scope=<fusion app scope>' \
  'https://idcs-abc123.identity.oraclecloud.com/oauth2/v1/token'
Enter fullscreen mode Exit fullscreen mode

The win over trusted-issuer JWT: central revocation, audit, token lifetime policy, and rotation live in the identity domain instead of your code.

401 vs 403 — the distinction that saves hours

  • 401 Unauthorized — Fusion doesn't know who you are: wrong password, expired token, clock skew on iat/exp, issuer certificate not uploaded, malformed header.
  • 403 Forbidden — Fusion knows who you are and says no: the integration user is missing the duty/job role for that resource, or data security scopes the user out of that business unit.
  • 404 on a real endpoint — sometimes authorization in disguise: a few resources return 404 instead of 403 when the user has no access. Check roles before doubting the URL.

If /workers returns 403 but /locations returns 200, your auth is fine — a role is missing. That's fixed in the Security Console, not in your code.

Choosing

  • Proof of concept → Basic Auth
  • Scheduled integration you own end-to-end → JWT trusted issuer
  • Production, multiple consumers, federation, anything user-facing → OAuth 2.0

And always: a dedicated integration user with minimum roles. Never run integrations as a personal account, and never grant broad roles to "make the 403s go away."

The full guide — with the complete setup steps, header examples, and troubleshooting table — is on our blog: Oracle Fusion REST API Authentication.

I build OPAL, an offline Oracle Fusion API explorer — 59,000+ HCM/FSCM endpoints searchable without internet, with visual q filter and finder builders and a full endpoint reference.

Top comments (0)