Oracle Fusion REST API Authentication: Basic Auth, JWT, and OAuth 2.0

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. This guide covers all three with working examples, and ends with the 401-vs-403 troubleshooting table that resolves most “authentication” tickets (spoiler: half of them are authorization problems, not authentication).

All examples use an anonymized pod (acme.fa.us2.oraclecloud.com) and placeholder users ([email protected]). Swap in your own hostname and credentials.

The three options at a glance

Method	Best for	Setup effort	Token expiry
Basic Auth over TLS	Development, testing, quick internal scripts	None	N/A (credentials sent per request)
JWT bearer (trusted issuer)	Server-to-server integrations you control	Medium — upload signing certificate once	You set it in the token (keep it short)
OAuth 2.0 via IDCS/IAM	Production integrations, third-party apps, user-context flows	Highest — register a confidential app	Managed by the identity domain

One rule that surprises people: 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.

Basic Auth over TLS

The simplest option and completely fine for development. Credentials travel base64-encoded in the Authorization header on every request, so TLS is mandatory (Fusion pods only serve HTTPS anyway).

curl -u '[email protected]:YourPassword' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?limit=5'

Or with an explicit header:

GET /hcmRestApi/resources/11.13.18.05/workers?limit=5
Authorization: Basic aW50ZWdyYXRpb24udXNlckBleGFtcGxlLmNvbTpZb3VyUGFzc3dvcmQ=

Drawbacks for production: passwords expire on the pod’s rotation policy (integrations break silently at 3 a.m.), credentials are replayable if leaked, and there is no scoping — the header is the full identity. Oracle’s own guidance is to move to OAuth 2.0 for anything long-lived.

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. No identity-domain round trip per request, no password rotation problem.

One-time setup in Fusion (Security Console → API Authentication):

1. Generate a key pair and an X.509 certificate for your issuer.
2. Create a JWT Issuer entry with your issuer name and upload the certificate.
3. Ensure the integration user exists in Fusion with the roles the integration needs.

Your system then builds a JWT per call (or per short session):

{
  "alg": "RS256", "typ": "JWT", "x5t": "<cert thumbprint>"
}
{
  "iss": "www.example.com",
  "prn": "[email protected]",
  "sub": "[email protected]",
  "iat": 1780000000,
  "exp": 1780000900
}

Sign it with your private key and send it as a bearer token:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  'https://acme.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices?limit=5'

The prn/sub claim must match an active Fusion username — that user’s roles are what the request runs with. Keep exp short (15 minutes is common); the token is self-contained, so a leaked one is valid until expiry.

OAuth 2.0 via IDCS / IAM identity domain

The production-grade option, and required when a third party (or Entra ID federation) is involved. Your Fusion instance has an associated Oracle identity domain (IDCS, or OCI IAM on newer tenancies) that issues tokens.

One-time setup in the identity domain console:

1. Register a confidential application.
2. Enable the grant types you need (client credentials + JWT user assertion for server-to-server; authorization code for user-facing apps).
3. Add the Fusion application resource scope to the app.
4. Note the client ID and secret.

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 should represent.

Token request:

curl -u '<client_id>:<client_secret>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -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'

Then use the returned token exactly like the JWT above:

curl -H "Authorization: Bearer <access_token>" \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?limit=5'

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

401 vs 403 — authentication vs authorization

The single most useful distinction when debugging:

Status	Meaning	Usual causes
401 Unauthorized	Fusion doesn’t know who you are	Wrong password, expired token, clock skew on iat/exp, issuer certificate not uploaded, malformed Authorization header
403 Forbidden	Fusion knows who you are and says no	Integration user missing the duty/job role for that resource, data security (the user’s role sees no rows in that business unit or legal entity)
404 on a real endpoint	Sometimes authorization in disguise	A few resources return 404 rather than 403 when the user has no access — check roles before doubting the URL

If you get a 401 with Basic Auth that worked yesterday, check password expiry first. If you get a 403 on /workers but 200 on /locations, the user is fine — the role is missing. Role setup happens in the Security Console, not in the API.

Which method should you use?

• Exploring the API, building a proof of concept → Basic Auth. Zero setup.
• A scheduled integration you own end-to-end → JWT trusted issuer. One certificate upload, no token service dependency.
• Production integrations, multiple consumers, federation (Entra ID, Okta), or anything user-facing → OAuth 2.0 through the identity domain.

Whatever you pick, create a dedicated integration user with the minimum roles the integration needs — never run integrations as a personal account, and never grant an integration user broad roles to “make the 403s go away.”

Testing authenticated requests faster

Once auth works, the slow part becomes figuring out what to call — which of the 59,000+ endpoints, which q fields, which finders. OPAL bundles the full HCM and FSCM catalogs offline in a searchable endpoint reference, stores your credentials locally encrypted (AES-256-GCM, no cloud), and sends live authenticated requests — Basic or token — without you hand-writing headers. The HCM examples post shows what those requests look like end to end, and the Oracle HCM API guide covers the HCM-side setup in more depth.

---

This post is part of our complete Oracle Fusion API guide — pillars, base URLs, authentication, q filters, finders, and common errors in one place.