INT eRS and Application Authenticated Issues

e-Referral Service (e-RS)
,
1

Hi team,

We’re integrating application-restricted (unattended) access to the e-Referral Service FHIR API in the Integration Test environment, and all our calls are failing with a 500 REC_SERVER_ERROR from the e-RS backend. We believe the remaining issue is server-side configuration and would appreciate your help.

Application details

Application name: FDSAPPLICATIONAUTHONLY

Application ID: cf907a72-9d48-4bcf-b3b3-bf6f48b97fee

Environment: Integration test

Connected API: e-Referral Service - Application Restricted (Integration Testing) — Enabled

Owner: FDS CIS2 TEAM

What we’ve configured and verified

Signed-JWT (RS512) client credentials authentication succeeds — we obtain an access token from https://int.api.service.nhs.uk/oauth2/token without errors.

The custom attributes asid, app-restricted-ods-code, and app-restricted-user-id are set on the application. We worked through the “Unresolved variable” gateway errors for each of these, so we know the attributes are now being resolved by the proxy.

Requests send only the Authorization header (no NHSD-End-User-Organisation-ODS or NHSD-eRS-Business-Function), per the application-restricted specification.

The problem

Every application-restricted endpoint we call returns 500 with REC_SERVER_ERROR, for example (all times UTC, 5 July 2026):

GET /referrals/FHIR/R4/HealthcareService/6710419 (A033) at 15:51:34 → 500 REC_SERVER_ERROR

GET /referrals/FHIR/R4/HealthcareService?_id=6710419 (A035) at 15:49:12 → 500 REC_SERVER_ERROR

GET /referrals/FHIR/STU3/ReferralRequest/9000000009 (A005) at ~15:53 → 500 (we’d expect a 404 here for an unknown UBRN, so the request appears to fail before resource lookup)

Service 6710419 exists in INT — we fetch it successfully via our user-restricted (Healthcare Worker) application.

Our suspicion

The asid attribute is currently set to 200000002295, which is the ASID accredited to our existing user-restricted application. Per your documentation, each access mode requires its own ASID with a one-to-one application binding, so we suspect this ASID isn’t accredited for application-restricted interactions and the Spine backend is rejecting the requests.

Request

Could you either provision/accredit an INT ASID for application-restricted access for this application, or correct the application’s backend setup as appropriate? Happy to provide correlation IDs or re-run test calls if that helps your investigation.

Our intended usage is read-only service lookup (A033/A035/A037) to support directory-of-service management in our application.

2

@Iain_Pretty

Iain, thanks for posting on the community - it is appreciated. I’ll ask a dev to take a look - a correlation ID would be useful if you have one.

My suspicion is that it is not the asid here (but you’re correct in your observation it is typically unique, and would be the case in production).

Where asid is at fault we usually see something more meaningful like “asid not found” or “permissions missing”.

Doesn’t seem like you’re getting that far in your initial call.

3

Hi Tony

Great to hear from you, and hope your well!

I’ve re-run the failing calls just now so you have fresh correlation IDs.

Environment: Integration (INT), int.api.service.nhs.uk Application: FDSAPPLICATIONAUTHONLY (application ID cf907a72-9d48-4bcf-b3b3-bf6f48b97fee), e-Referral Service – Application Restricted enabled. Custom attributes set: asid = 200000002295, app-restricted-ods-code = D81045, app-restricted-user-id = 555249469106.

What happens: signed-JWT client-credentials token acquisition succeeds (HTTP 200), and the request reaches e-RS (the earlier gateway “Unresolved variable” errors for each custom attribute are all resolved). Every application-restricted call then fails with HTTP 500. The R4 endpoints return an OperationOutcome (severity: error, code: exception, coding REC_SERVER_ERROR from https://fhir.nhs.uk/CodeSystem/http-error-codes); the STU3 call returns a 500 with an empty body. Requests send only the Authorization header plus X-Correlation-Id, per the application-restricted spec.

Three failing requests, all on 8 Jul 2026 at 10:04:02 UTC:

  1. GET /referrals/FHIR/STU3/ReferralRequest/9000000009 (control test — expected 404 for unknown UBRN, got 500, empty body) X-Correlation-ID: 5a0e7832-ffa3-48f4-bbf8-222188b3e05e · X-Request-ID: eb8b336d-10c3-42c2-b3e0-ac62622de051-1
  2. GET /referrals/FHIR/R4/HealthcareService/6710419 — 500 REC_SERVER_ERROR X-Correlation-ID: 052d8393-a522-4041-b21f-c01634faadcf · X-Request-ID: f0e2d5d4-e211-49f5-8f3a-aa79ef2f7deb-1
  3. GET /referrals/FHIR/R4/HealthcareService?_id=6710419 — 500 REC_SERVER_ERROR X-Correlation-ID: 3bd14854-b768-4e1f-a1f8-f6a9b6faba64 · X-Request-ID: ea68b149-7a08-4542-9959-22b1772c9fd1-1

Service 6710419 is one we can fetch successfully via the user-restricted route, so the resource itself exists in INT. Happy to re-run with any variations if that helps your dev — the probe takes seconds on our side.

Thanks again for all your help

Cheers

Iain

4

Hi Iain,

So something slightly odd happening. The SDS Gateway is throwing an error when searching for the UUID in question.

From previous communications, it looks like the UUID was stated as being one you already had - so the ITOC team were just updating it with the test org, to allow you to begin testing.

Is the UUID you supplier (555249469106) definitely INT?

5

Hi Tony!

Thanks for looking into this; your SDS Gateway lead was spot on. We’ve worked through the identifier issue on our side and can now see a clear change in behaviour. Summary below for your dev/ITOC.

What we were seeing

Application: FDSAPPLICATIONAUTHONLY
Application ID: cf907a72-9d48-4bcf-b3b3-bf6f48b97fee
Environment: Integration test (int.api.service.nhs.uk)

With application-restricted client-credentials auth, token acquisition succeeded (HTTP 200) but every e-RS call failed with HTTP 500 and REC_SERVER_ERROR OperationOutcomes (or empty body on STU3). This matched your observation that the SDS Gateway was erroring when searching for the UUID we had configured.

Steps we took (and what each proved)

1. Original app-restricted-user-id: 555249469106

This value came from our own live CIS2 INT logins — it is the Role Profile ID (URPID / person_roleid) for a “General Medical Practitioner @ D81045” role held by test user Mr SUPPORT THIRTYTHREE, captured during CIS2 role selection in our application (INT logs, 2–3 July 2026). So it is an INT identifier, but it belongs to a different test user than the one we are using now.

Probe result: identical 500 REC_SERVER_ERROR on all calls.

2. First change — swapped to 555398427107 (Joe Four)

We believed this was Joe Four’s INT identity from our triage audit table. Re-ran probes three times over ~7 minutes (18:06–18:13 UTC, 8 July).

Probe result: still 500 REC_SERVER_ERROR — no change.

Later finding: 555398427107 is not Joe Four’s D81045 identity. It is his Consultant @ E7R3G role profile from an earlier service-provider session — wrong org/role pairing for our app config (app-restricted-ods-code = D81045).

3. Second change — 555398419104 (Joe Four @ D81045 role URPID)

After Joe Four logged into INT today as Referring clinician @ ERS API GPP 39 (ODS D81045), we extracted his role list and set the hub to his D81045 Referring clinician Role Profile ID: 555398419104.

Probe result: still 500 REC_SERVER_ERROR.

This suggested the SDS lookup may not be keyed on role profile IDs (URPIDs) at all.

4. Final change — 555398387103 (Joe Four user-level UUID) ✓

From the same live CIS2 INT login (Joe Four, Referring clinician, D81045), we extracted his user-level UUID from the CIS2 token (uid / sub / nhsid_useruid): 555398387103.

We updated app-restricted-user-id to this value and re-ran the probe at 18:43 UTC, 8 July 2026.

Probe result — behaviour changed:

Call Endpoint HTTP Outcome
A005 (control) GET /referrals/FHIR/STU3/ReferralRequest/9000000009 404 Request reached e-RS; unknown UBRN correctly not found
A033 GET /referrals/FHIR/R4/HealthcareService/6710419 403 REC_FORBIDDEN — “Endpoint not authorised for Business Function (PROVIDER_AUTHORISED_APPLICATION)”
A035 GET /referrals/FHIR/R4/HealthcareService?_id=6710419 403 Same as A033

Correlation IDs (18:43 UTC run):

  • A005: X-Correlation-ID d7d54eb0-e6c2-4867-83b9-4c4b5ab62c66 · X-Request-ID acc6fd5a-943d-4651-9fd1-dd6b9070fac7-1
  • A033: X-Correlation-ID 1d1a15ce-996d-4e7b-9fa3-2d6bf5762e65 · X-Request-ID 7a04c429-e4cf-4dda-9474-05583eaa7ce2-1
  • A035: X-Correlation-ID c6154582-c10e-4a7b-ae83-71c290f4d623 · X-Request-ID 505250f3-e058-45ed-85da-7424758d1a35-1

We interpret this as: the SDS lookup issue is resolved (no more 500s). The remaining 403s look like a permissions / business-function step rather than SDS failure.

The URID / UUID distinction (likely root cause)

All values we initially supplied were CIS2 Role Profile IDs (URPIDs) from nhsid_nrbac_roles[].person_roleid — i.e. a role at an organisation, not the user themselves.

Value Type Who / what
555249469106 URPID SUPPORT THIRTYTHREE — GMP @ D81045
555398427107 URPID Joe Four — Consultant @ E7R3G (wrong org for our config)
555398419104 URPID Joe Four — Referring clinician @ D81045
555398387103 User UUID Joe Four — user-level identity

Only the user-level UUID (555398387103) cleared the SDS gateway error. Could you confirm that app-restricted-user-id must carry the user UUID (nhsid_useruid / uid), not a role profile ID? If so, it would help to document that clearly for application-restricted onboarding — we had assumed a URID from CIS2 login was the correct value.

Final hub configuration (current)

Custom attribute Value Notes
asid 200000002295 Unchanged
app-restricted-ods-code D81045 Matches Joe Four’s Referring clinician login (ERS API GPP 39) — we have not changed this
app-restricted-user-id 555398387103 Joe Four user-level UUID from live CIS2 INT login today

Application ID: cf907a72-9d48-4bcf-b3b3-bf6f48b97fee — unchanged.

We are not planning to change ODS or Application ID unless you advise otherwise.

What we need from you / ITOC

  1. Confirm app-restricted-user-id should be the user UUID, not a URPID.
  2. Associate Joe Four (user UUID 555398387103) with the test organisation for application-restricted access at D81045, so A033/A035 are authorised (or advise the correct business function for HealthcareService lookup under application-restricted auth — we currently see PROVIDER_AUTHORISED_APPLICATION rejected).
  3. Once association is done, we’ll re-probe and share fresh correlation IDs.

Sorry for the lengthy email but wanted to share the steps we had taken - even if many of them were in the wrong direction!

Thanks as always for your help

Iain

6

Iain

Sorry for the radio silence, we have a weekly meeting tomorrow to review forum questions I’ll chat about this then and respond

7

@Iain_Pretty

Hey Iain,

I can confirm that app-restricted-user-id should be the user UUID and not URPID, we will take action to update this in the onboarding. Also regarding the 403 errors, there is a small setup step needing change that we will do on our side, this should solve your problem.

Kind regards,

George

8

@Iain_Pretty I’ve made a request this morning for the app to be changed - i’ll let you know when it has, usually takes around 24hours.

9

@Iain_Pretty

That change has been amended - ready to re-test

10

Hi Tony!

Thank you for resolving the application-restricted setup for our INT application — much appreciated.

What is working now

Using Developer Hub application FDSAPPLICATIONAUTHONLY (cf907a72-9d48-4bcf-b3b3-bf6f48b97fee) with signed-JWT client credentials and custom attributes asid = 200000002295, app-restricted-ods-code = D81045, app-restricted-user-id = 555398387103 (user-level UUID), we can successfully call:

  • A004 — Retrieve reference data
  • A033 / A035 / A037 — Healthcare service retrieve / search / version

These return 200 as expected. The application is acting as REFERRER_AUTHORISED_APPLICATION, which is correct for our unattended directory / service-lookup use case.

What we still need

We also need application-restricted provider access at the same time (for example A008 worklists, and related referral-scoped calls). Per your Stage 4 guidance, referrer and provider application-restricted capabilities require separate ASIDs / applications, and we understand a single app cannot hold both.

Could you please help us set up a second INT application-restricted (provider) configuration so we can run both simultaneously alongside the existing referrer app?

Specifically, we would like:

  1. A new INT ASID for application-restricted provider use (we will not reuse 200000002295).
  2. Confirmation of the correct Hub setup for that second app (API product, custom attributes, and any ITOC / org association steps).
  3. Guidance on the recommended INT provider identity pair — we intend to use ODS E7R3G (TD008807 TEST TRUST 015), which we already use successfully for user-restricted provider work via CIS2. Please advise if a different trust ODS / user UUID is preferred for app-restricted provider.
  4. Any forms or EUO responsibilities we need to complete for the provider connection.

Once we have the new ASID and association details, we will create the second Developer Hub application, point it at our existing JWKS, and re-test A008 (and related provider endpoints) under the new identity while keeping the current referrer app for A004/A033/A035/A037.

Happy to provide correlation IDs from our successful probes if useful.

Thanks again for the fix and for your help with the second round!

Cheers
Iain

11

Hi Iain,

So you are correct you’ll need an app for each auth type, x3 if user restricted + provider + referrer app restricted.

Could you post the app IDs once you created them for INT env.