From f4fb98a0de510689e9c3296050f4fa9924b97c9f Mon Sep 17 00:00:00 2001
From: David Wass <david.wass2@nhs.net>
Date: Fri, 5 Dec 2025 10:53:52 +0000
Subject: [PATCH 1/4] CCM-12673 - Make PR proxies temporary

---
 .gitignore                                    |  1 +
 Makefile                                      |  4 +--
 scripts/build/substitute_build_env.sh         | 26 +++++++++++++++++++
 .../x-nhsd-apim/access-template.yml           |  1 -
 .../api/components/x-nhsd-apim/access.yml     |  1 -
 .../api/components/x-nhsd-apim/int.env        |  3 +++
 .../{access-int.yml => int/access.yml}        |  0
 .../x-nhsd-apim/{ => int}/rate-limiting.yml   |  0
 .../{ => int}/target-attributes.yml           |  0
 .../{target-int.yml => int/target.yml}        |  0
 .../x-nhsd-apim/internal-dev-pr.env           |  3 +++
 .../access.yml}                               |  0
 .../internal-dev-pr/rate-limiting.yml         |  3 +++
 .../internal-dev-pr/target-attributes.yml     |  3 +++
 .../target.yml}                               |  0
 .../components/x-nhsd-apim/internal-dev.env   |  3 +++
 .../access.yml}                               |  0
 .../internal-dev/rate-limiting.yml            |  3 +++
 .../internal-dev/target-attributes.yml        |  3 +++
 .../target.yml}                               |  0
 .../api/components/x-nhsd-apim/prod.env       |  3 +++
 .../{access-prod.yml => prod/access.yml}      |  0
 .../x-nhsd-apim/prod/rate-limiting.yml        |  3 +++
 .../x-nhsd-apim/prod/target-attributes.yml    |  3 +++
 .../{target-prod.yml => prod/target.yml}      |  0
 .../api/components/x-nhsd-apim/ref.env        |  3 +++
 .../{access-ref.yml => ref/access.yml}        |  0
 .../x-nhsd-apim/ref/rate-limiting.yml         |  3 +++
 .../x-nhsd-apim/ref/target-attributes.yml     |  3 +++
 .../{target-ref.yml => ref/target.yml}        |  0
 .../api/components/x-nhsd-apim/sandbox.env    |  3 +++
 .../access.yml}                               |  0
 .../x-nhsd-apim/sandbox/rate-limiting.yml     |  3 +++
 .../x-nhsd-apim/sandbox/target-attributes.yml |  3 +++
 .../target.yml}                               |  0
 .../x-nhsd-apim/target-template.yml           |  1 -
 .../api/components/x-nhsd-apim/target.yml     |  1 -
 .../x-nhsd-apim/x-nhsd-apim-template.yml      | 10 +++++++
 specification/api/notify-supplier-phase1.yml  | 11 +-------
 39 files changed, 88 insertions(+), 16 deletions(-)
 create mode 100755 scripts/build/substitute_build_env.sh
 delete mode 100644 specification/api/components/x-nhsd-apim/access-template.yml
 delete mode 100644 specification/api/components/x-nhsd-apim/access.yml
 create mode 100644 specification/api/components/x-nhsd-apim/int.env
 rename specification/api/components/x-nhsd-apim/{access-int.yml => int/access.yml} (100%)
 rename specification/api/components/x-nhsd-apim/{ => int}/rate-limiting.yml (100%)
 rename specification/api/components/x-nhsd-apim/{ => int}/target-attributes.yml (100%)
 rename specification/api/components/x-nhsd-apim/{target-int.yml => int/target.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/internal-dev-pr.env
 rename specification/api/components/x-nhsd-apim/{access-internal-dev-pr.yml => internal-dev-pr/access.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/internal-dev-pr/rate-limiting.yml
 create mode 100644 specification/api/components/x-nhsd-apim/internal-dev-pr/target-attributes.yml
 rename specification/api/components/x-nhsd-apim/{target-internal-dev-pr.yml => internal-dev-pr/target.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/internal-dev.env
 rename specification/api/components/x-nhsd-apim/{access-internal-dev.yml => internal-dev/access.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/internal-dev/rate-limiting.yml
 create mode 100644 specification/api/components/x-nhsd-apim/internal-dev/target-attributes.yml
 rename specification/api/components/x-nhsd-apim/{target-internal-dev.yml => internal-dev/target.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/prod.env
 rename specification/api/components/x-nhsd-apim/{access-prod.yml => prod/access.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/prod/rate-limiting.yml
 create mode 100644 specification/api/components/x-nhsd-apim/prod/target-attributes.yml
 rename specification/api/components/x-nhsd-apim/{target-prod.yml => prod/target.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/ref.env
 rename specification/api/components/x-nhsd-apim/{access-ref.yml => ref/access.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/ref/rate-limiting.yml
 create mode 100644 specification/api/components/x-nhsd-apim/ref/target-attributes.yml
 rename specification/api/components/x-nhsd-apim/{target-ref.yml => ref/target.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/sandbox.env
 rename specification/api/components/x-nhsd-apim/{access-sandbox.yml => sandbox/access.yml} (100%)
 create mode 100644 specification/api/components/x-nhsd-apim/sandbox/rate-limiting.yml
 create mode 100644 specification/api/components/x-nhsd-apim/sandbox/target-attributes.yml
 rename specification/api/components/x-nhsd-apim/{target-sandbox.yml => sandbox/target.yml} (100%)
 delete mode 100644 specification/api/components/x-nhsd-apim/target-template.yml
 delete mode 100644 specification/api/components/x-nhsd-apim/target.yml
 create mode 100644 specification/api/components/x-nhsd-apim/x-nhsd-apim-template.yml

diff --git a/.gitignore b/.gitignore
index 7bebffb1..530cfc0a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,4 +27,5 @@ dist
 /sandbox/*.log
 /sandbox-staging
 /specification/api/components/examples
+/specification/api/components/x-nhsd-apim/x-nhsd-apim.yml
 /scripts/JWT/*.pem
diff --git a/Makefile b/Makefile
index dacd22f5..79eb8edb 100644
--- a/Makefile
+++ b/Makefile
@@ -69,9 +69,9 @@ set-security: guard-APIM_ENV
 	< specification/api/components/security-schemes/security-schemes-template.yml > specification/api/components/security-schemes/security-schemes.yml
 
 construct-spec: guard-APIM_ENV
+	SPEC_DIR=./specification/api/components/x-nhsd-apim
+	./scripts/build/substitute_build_env.sh $$SPEC_DIR/x-nhsd-apim-template.yml $$SPEC_DIR/$$APIM_ENV.env $$SPEC_DIR/x-nhsd-apim.yml
 	$(MAKE) set-authorization APIM_ENV=$$APIM_ENV
-	$(MAKE) set-target APIM_ENV=$$APIM_ENV
-	$(MAKE) set-access APIM_ENV=$$APIM_ENV
 	$(MAKE) set-security APIM_ENV=$$APIM_ENV
 
 build-json-oas-spec: guard-APIM_ENV
diff --git a/scripts/build/substitute_build_env.sh b/scripts/build/substitute_build_env.sh
new file mode 100755
index 00000000..f11f3bf3
--- /dev/null
+++ b/scripts/build/substitute_build_env.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TEMPLATE="$1"
+ENV_FILE="$2"
+OUT="$3"
+
+# Extract variable names from the env file (left side of KEY=VALUE)
+VARS=$(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "$ENV_FILE" | cut -d= -f1)
+
+# Build envsubst variable list ($VAR1 $VAR2 ...)
+VARLIST=""
+for v in $VARS; do
+  VARLIST="$VARLIST \$$v"
+done
+VARLIST="${VARLIST# }"   # remove leading space
+
+# Export values from the env file
+set -a
+source "$ENV_FILE"
+set +a
+
+# Run envsubst only on the selected variables
+envsubst "$VARLIST" < "$TEMPLATE" > "$OUT"
+
+echo "Generated: $OUT"
diff --git a/specification/api/components/x-nhsd-apim/access-template.yml b/specification/api/components/x-nhsd-apim/access-template.yml
deleted file mode 100644
index cee5c6f0..00000000
--- a/specification/api/components/x-nhsd-apim/access-template.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: $ACCESS
diff --git a/specification/api/components/x-nhsd-apim/access.yml b/specification/api/components/x-nhsd-apim/access.yml
deleted file mode 100644
index c69c222d..00000000
--- a/specification/api/components/x-nhsd-apim/access.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: access-prod.yml
diff --git a/specification/api/components/x-nhsd-apim/int.env b/specification/api/components/x-nhsd-apim/int.env
new file mode 100644
index 00000000..03fb81fc
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/int.env
@@ -0,0 +1,3 @@
+MONITORING_FLAG=false
+TEMPORARY_FLAG=false
+ENV_DIR=./int
diff --git a/specification/api/components/x-nhsd-apim/access-int.yml b/specification/api/components/x-nhsd-apim/int/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/access-int.yml
rename to specification/api/components/x-nhsd-apim/int/access.yml
diff --git a/specification/api/components/x-nhsd-apim/rate-limiting.yml b/specification/api/components/x-nhsd-apim/int/rate-limiting.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/rate-limiting.yml
rename to specification/api/components/x-nhsd-apim/int/rate-limiting.yml
diff --git a/specification/api/components/x-nhsd-apim/target-attributes.yml b/specification/api/components/x-nhsd-apim/int/target-attributes.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/target-attributes.yml
rename to specification/api/components/x-nhsd-apim/int/target-attributes.yml
diff --git a/specification/api/components/x-nhsd-apim/target-int.yml b/specification/api/components/x-nhsd-apim/int/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/target-int.yml
rename to specification/api/components/x-nhsd-apim/int/target.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev-pr.env b/specification/api/components/x-nhsd-apim/internal-dev-pr.env
new file mode 100644
index 00000000..e8820a5e
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/internal-dev-pr.env
@@ -0,0 +1,3 @@
+MONITORING_FLAG=false
+TEMPORARY_FLAG=true
+ENV_DIR=./internal-dev-pr
diff --git a/specification/api/components/x-nhsd-apim/access-internal-dev-pr.yml b/specification/api/components/x-nhsd-apim/internal-dev-pr/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/access-internal-dev-pr.yml
rename to specification/api/components/x-nhsd-apim/internal-dev-pr/access.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev-pr/rate-limiting.yml b/specification/api/components/x-nhsd-apim/internal-dev-pr/rate-limiting.yml
new file mode 100644
index 00000000..71900a20
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/internal-dev-pr/rate-limiting.yml
@@ -0,0 +1,3 @@
+app-default:
+  limit: 300
+  timeunit: second
diff --git a/specification/api/components/x-nhsd-apim/internal-dev-pr/target-attributes.yml b/specification/api/components/x-nhsd-apim/internal-dev-pr/target-attributes.yml
new file mode 100644
index 00000000..d2abc241
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/internal-dev-pr/target-attributes.yml
@@ -0,0 +1,3 @@
+- name: NHSD-Supplier-ID
+  header: NHSD-Supplier-ID
+  required: true
diff --git a/specification/api/components/x-nhsd-apim/target-internal-dev-pr.yml b/specification/api/components/x-nhsd-apim/internal-dev-pr/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/target-internal-dev-pr.yml
rename to specification/api/components/x-nhsd-apim/internal-dev-pr/target.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev.env b/specification/api/components/x-nhsd-apim/internal-dev.env
new file mode 100644
index 00000000..891efe3a
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/internal-dev.env
@@ -0,0 +1,3 @@
+MONITORING_FLAG=false
+TEMPORARY_FLAG=false
+ENV_DIR=./internal-dev
diff --git a/specification/api/components/x-nhsd-apim/access-internal-dev.yml b/specification/api/components/x-nhsd-apim/internal-dev/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/access-internal-dev.yml
rename to specification/api/components/x-nhsd-apim/internal-dev/access.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev/rate-limiting.yml b/specification/api/components/x-nhsd-apim/internal-dev/rate-limiting.yml
new file mode 100644
index 00000000..71900a20
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/internal-dev/rate-limiting.yml
@@ -0,0 +1,3 @@
+app-default:
+  limit: 300
+  timeunit: second
diff --git a/specification/api/components/x-nhsd-apim/internal-dev/target-attributes.yml b/specification/api/components/x-nhsd-apim/internal-dev/target-attributes.yml
new file mode 100644
index 00000000..d2abc241
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/internal-dev/target-attributes.yml
@@ -0,0 +1,3 @@
+- name: NHSD-Supplier-ID
+  header: NHSD-Supplier-ID
+  required: true
diff --git a/specification/api/components/x-nhsd-apim/target-internal-dev.yml b/specification/api/components/x-nhsd-apim/internal-dev/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/target-internal-dev.yml
rename to specification/api/components/x-nhsd-apim/internal-dev/target.yml
diff --git a/specification/api/components/x-nhsd-apim/prod.env b/specification/api/components/x-nhsd-apim/prod.env
new file mode 100644
index 00000000..a05318ea
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/prod.env
@@ -0,0 +1,3 @@
+MONITORING_FLAG=false
+TEMPORARY_FLAG=false
+ENV_DIR=./prod
diff --git a/specification/api/components/x-nhsd-apim/access-prod.yml b/specification/api/components/x-nhsd-apim/prod/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/access-prod.yml
rename to specification/api/components/x-nhsd-apim/prod/access.yml
diff --git a/specification/api/components/x-nhsd-apim/prod/rate-limiting.yml b/specification/api/components/x-nhsd-apim/prod/rate-limiting.yml
new file mode 100644
index 00000000..71900a20
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/prod/rate-limiting.yml
@@ -0,0 +1,3 @@
+app-default:
+  limit: 300
+  timeunit: second
diff --git a/specification/api/components/x-nhsd-apim/prod/target-attributes.yml b/specification/api/components/x-nhsd-apim/prod/target-attributes.yml
new file mode 100644
index 00000000..d2abc241
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/prod/target-attributes.yml
@@ -0,0 +1,3 @@
+- name: NHSD-Supplier-ID
+  header: NHSD-Supplier-ID
+  required: true
diff --git a/specification/api/components/x-nhsd-apim/target-prod.yml b/specification/api/components/x-nhsd-apim/prod/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/target-prod.yml
rename to specification/api/components/x-nhsd-apim/prod/target.yml
diff --git a/specification/api/components/x-nhsd-apim/ref.env b/specification/api/components/x-nhsd-apim/ref.env
new file mode 100644
index 00000000..a2796e9a
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/ref.env
@@ -0,0 +1,3 @@
+MONITORING_FLAG=false
+TEMPORARY_FLAG=false
+ENV_DIR=./ref
diff --git a/specification/api/components/x-nhsd-apim/access-ref.yml b/specification/api/components/x-nhsd-apim/ref/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/access-ref.yml
rename to specification/api/components/x-nhsd-apim/ref/access.yml
diff --git a/specification/api/components/x-nhsd-apim/ref/rate-limiting.yml b/specification/api/components/x-nhsd-apim/ref/rate-limiting.yml
new file mode 100644
index 00000000..71900a20
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/ref/rate-limiting.yml
@@ -0,0 +1,3 @@
+app-default:
+  limit: 300
+  timeunit: second
diff --git a/specification/api/components/x-nhsd-apim/ref/target-attributes.yml b/specification/api/components/x-nhsd-apim/ref/target-attributes.yml
new file mode 100644
index 00000000..d2abc241
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/ref/target-attributes.yml
@@ -0,0 +1,3 @@
+- name: NHSD-Supplier-ID
+  header: NHSD-Supplier-ID
+  required: true
diff --git a/specification/api/components/x-nhsd-apim/target-ref.yml b/specification/api/components/x-nhsd-apim/ref/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/target-ref.yml
rename to specification/api/components/x-nhsd-apim/ref/target.yml
diff --git a/specification/api/components/x-nhsd-apim/sandbox.env b/specification/api/components/x-nhsd-apim/sandbox.env
new file mode 100644
index 00000000..d4a1435e
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/sandbox.env
@@ -0,0 +1,3 @@
+MONITORING_FLAG=false
+TEMPORARY_FLAG=false
+ENV_DIR=./sandbox
diff --git a/specification/api/components/x-nhsd-apim/access-sandbox.yml b/specification/api/components/x-nhsd-apim/sandbox/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/access-sandbox.yml
rename to specification/api/components/x-nhsd-apim/sandbox/access.yml
diff --git a/specification/api/components/x-nhsd-apim/sandbox/rate-limiting.yml b/specification/api/components/x-nhsd-apim/sandbox/rate-limiting.yml
new file mode 100644
index 00000000..71900a20
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/sandbox/rate-limiting.yml
@@ -0,0 +1,3 @@
+app-default:
+  limit: 300
+  timeunit: second
diff --git a/specification/api/components/x-nhsd-apim/sandbox/target-attributes.yml b/specification/api/components/x-nhsd-apim/sandbox/target-attributes.yml
new file mode 100644
index 00000000..74d901d1
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/sandbox/target-attributes.yml
@@ -0,0 +1,3 @@
+- name: NHSD-Supplier-ID
+  header: NHSD-Supplier-ID
+  required: false
diff --git a/specification/api/components/x-nhsd-apim/target-sandbox.yml b/specification/api/components/x-nhsd-apim/sandbox/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/target-sandbox.yml
rename to specification/api/components/x-nhsd-apim/sandbox/target.yml
diff --git a/specification/api/components/x-nhsd-apim/target-template.yml b/specification/api/components/x-nhsd-apim/target-template.yml
deleted file mode 100644
index b3eebe5c..00000000
--- a/specification/api/components/x-nhsd-apim/target-template.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: $TARGET
diff --git a/specification/api/components/x-nhsd-apim/target.yml b/specification/api/components/x-nhsd-apim/target.yml
deleted file mode 100644
index a0f578ca..00000000
--- a/specification/api/components/x-nhsd-apim/target.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: target-prod.yml
diff --git a/specification/api/components/x-nhsd-apim/x-nhsd-apim-template.yml b/specification/api/components/x-nhsd-apim/x-nhsd-apim-template.yml
new file mode 100644
index 00000000..8edb1b04
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/x-nhsd-apim-template.yml
@@ -0,0 +1,10 @@
+temporary: $TEMPORARY_FLAG
+monitoring: $MONITORING_FLAG
+access:
+  $ref: $ENV_DIR/access.yml
+target:
+  $ref: $ENV_DIR/target.yml
+target-attributes:
+  $ref: $ENV_DIR/target-attributes.yml
+ratelimiting:
+  $ref: $ENV_DIR/rate-limiting.yml
diff --git a/specification/api/notify-supplier-phase1.yml b/specification/api/notify-supplier-phase1.yml
index 9588b820..2e26e8b7 100644
--- a/specification/api/notify-supplier-phase1.yml
+++ b/specification/api/notify-supplier-phase1.yml
@@ -68,13 +68,4 @@ servers:
   - url: 'http://127.0.0.1:9000'
     description: Local development server
 x-nhsd-apim:
-  temporary: false
-  monitoring: false
-  access:
-    $ref: ./components/x-nhsd-apim/access.yml
-  target:
-    $ref: ./components/x-nhsd-apim/target.yml
-  target-attributes:
-    $ref: ./components/x-nhsd-apim/target-attributes.yml
-  ratelimiting:
-    $ref: ./components/x-nhsd-apim/rate-limiting.yml
+  $ref: './components/x-nhsd-apim/x-nhsd-apim.yml'

From 11f3e14ee307c989b0ffdce01e541372533c9cd0 Mon Sep 17 00:00:00 2001
From: David Wass <david.wass2@nhs.net>
Date: Fri, 5 Dec 2025 14:12:35 +0000
Subject: [PATCH 2/4] Another refactor and include security

---
 .gitignore                                    |  3 ++
 Makefile                                      | 34 ++++++++-----------
 .../common}/security-schemes-ptl.yml          |  0
 .../{x-nhsd-apim => environments}/int.env     |  2 +-
 .../int/access.yml                            |  0
 .../int/authorization.yml}                    |  0
 .../int/rate-limiting.yml                     |  0
 .../environments/int/security-schemes.yml     |  1 +
 .../int/security.yml}                         |  0
 .../int/target-attributes.yml                 |  0
 .../int/target.yml                            |  0
 .../internal-dev-pr.env                       |  2 +-
 .../internal-dev-pr/access.yml                |  0
 .../internal-dev-pr/authorization.yml}        |  0
 .../internal-dev-pr/rate-limiting.yml         |  0
 .../internal-dev-pr/security-schemes.yml      |  1 +
 .../internal-dev-pr/security.yml}             |  0
 .../internal-dev-pr/target-attributes.yml     |  0
 .../internal-dev-pr/target.yml                |  0
 .../internal-dev.env                          |  2 +-
 .../internal-dev/access.yml                   |  0
 .../internal-dev/authorization.yml}           |  0
 .../internal-dev/rate-limiting.yml            |  0
 .../internal-dev/security-schemes.yml         |  1 +
 .../environments/internal-dev/security.yml    |  1 +
 .../internal-dev/target-attributes.yml        |  0
 .../internal-dev/target.yml                   |  0
 .../api/components/environments/prod.env      |  3 ++
 .../prod/access.yml                           |  0
 .../prod/authorization.yml}                   |  0
 .../prod/rate-limiting.yml                    |  0
 .../prod/security-schemes.yml}                |  0
 .../components/environments/prod/security.yml |  1 +
 .../prod/target-attributes.yml                |  0
 .../prod/target.yml                           |  0
 .../{x-nhsd-apim => environments}/ref.env     |  2 +-
 .../ref/access.yml                            |  0
 .../ref/authorization.yml}                    |  2 +-
 .../ref/rate-limiting.yml                     |  0
 .../environments/ref/security-schemes.yml     |  1 +
 .../components/environments/ref/security.yml  |  1 +
 .../ref/target-attributes.yml                 |  0
 .../ref/target.yml                            |  0
 .../{x-nhsd-apim => environments}/sandbox.env |  2 +-
 .../sandbox/access.yml                        |  0
 .../sandbox/authorization.yml}                |  2 +-
 .../sandbox/rate-limiting.yml                 |  0
 .../environments/sandbox/security-schemes.yml |  1 +
 .../sandbox/security.yml}                     |  0
 .../sandbox/target-attributes.yml             |  0
 .../sandbox/target.yml                        |  0
 .../authorization/authorization-template.yml  |  2 +-
 .../authorization/authorization.yml           |  1 -
 .../security-schemes/security-schemes-int.yml |  1 -
 .../security-schemes-internal-dev-pr.yml      |  1 -
 .../security-schemes-internal-dev.yml         |  1 -
 .../security-schemes/security-schemes-ref.yml |  1 -
 .../security-schemes-sandbox.yml              |  1 -
 .../security-schemes-template.yml             |  2 +-
 .../security-schemes/security-schemes.yml     |  1 -
 .../security/security-internal-dev.yml        |  1 -
 .../api/components/security/security-prod.yml |  1 -
 .../api/components/security/security-ref.yml  |  1 -
 .../components/security/security-template.yml |  2 +-
 .../api/components/security/security.yml      |  1 -
 .../api/components/x-nhsd-apim/prod.env       |  3 --
 66 files changed, 38 insertions(+), 44 deletions(-)
 rename specification/api/components/{security-schemes => environments/common}/security-schemes-ptl.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/int.env (60%)
 rename specification/api/components/{x-nhsd-apim => environments}/int/access.yml (100%)
 rename specification/api/components/{parameters/authorization/authorization-int.yml => environments/int/authorization.yml} (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/int/rate-limiting.yml (100%)
 create mode 100644 specification/api/components/environments/int/security-schemes.yml
 rename specification/api/components/{security/security-int.yml => environments/int/security.yml} (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/int/target-attributes.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/int/target.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev-pr.env (51%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev-pr/access.yml (100%)
 rename specification/api/components/{parameters/authorization/authorization-internal-dev-pr.yml => environments/internal-dev-pr/authorization.yml} (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev-pr/rate-limiting.yml (100%)
 create mode 100644 specification/api/components/environments/internal-dev-pr/security-schemes.yml
 rename specification/api/components/{security/security-internal-dev-pr.yml => environments/internal-dev-pr/security.yml} (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev-pr/target-attributes.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev-pr/target.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev.env (53%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev/access.yml (100%)
 rename specification/api/components/{parameters/authorization/authorization-prod.yml => environments/internal-dev/authorization.yml} (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev/rate-limiting.yml (100%)
 create mode 100644 specification/api/components/environments/internal-dev/security-schemes.yml
 create mode 100644 specification/api/components/environments/internal-dev/security.yml
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev/target-attributes.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/internal-dev/target.yml (100%)
 create mode 100644 specification/api/components/environments/prod.env
 rename specification/api/components/{x-nhsd-apim => environments}/prod/access.yml (100%)
 rename specification/api/components/{parameters/authorization/authorization-ref.yml => environments/prod/authorization.yml} (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/prod/rate-limiting.yml (100%)
 rename specification/api/components/{security-schemes/security-schemes-prod.yml => environments/prod/security-schemes.yml} (100%)
 create mode 100644 specification/api/components/environments/prod/security.yml
 rename specification/api/components/{x-nhsd-apim => environments}/prod/target-attributes.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/prod/target.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/ref.env (60%)
 rename specification/api/components/{x-nhsd-apim => environments}/ref/access.yml (100%)
 rename specification/api/components/{parameters/authorization/authorization-internal-dev.yml => environments/ref/authorization.yml} (93%)
 rename specification/api/components/{x-nhsd-apim => environments}/ref/rate-limiting.yml (100%)
 create mode 100644 specification/api/components/environments/ref/security-schemes.yml
 create mode 100644 specification/api/components/environments/ref/security.yml
 rename specification/api/components/{x-nhsd-apim => environments}/ref/target-attributes.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/ref/target.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/sandbox.env (57%)
 rename specification/api/components/{x-nhsd-apim => environments}/sandbox/access.yml (100%)
 rename specification/api/components/{parameters/authorization/authorization-sandbox.yml => environments/sandbox/authorization.yml} (93%)
 rename specification/api/components/{x-nhsd-apim => environments}/sandbox/rate-limiting.yml (100%)
 create mode 100644 specification/api/components/environments/sandbox/security-schemes.yml
 rename specification/api/components/{security/security-sandbox.yml => environments/sandbox/security.yml} (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/sandbox/target-attributes.yml (100%)
 rename specification/api/components/{x-nhsd-apim => environments}/sandbox/target.yml (100%)
 delete mode 100644 specification/api/components/parameters/authorization/authorization.yml
 delete mode 100644 specification/api/components/security-schemes/security-schemes-int.yml
 delete mode 100644 specification/api/components/security-schemes/security-schemes-internal-dev-pr.yml
 delete mode 100644 specification/api/components/security-schemes/security-schemes-internal-dev.yml
 delete mode 100644 specification/api/components/security-schemes/security-schemes-ref.yml
 delete mode 100644 specification/api/components/security-schemes/security-schemes-sandbox.yml
 delete mode 100644 specification/api/components/security-schemes/security-schemes.yml
 delete mode 100644 specification/api/components/security/security-internal-dev.yml
 delete mode 100644 specification/api/components/security/security-prod.yml
 delete mode 100644 specification/api/components/security/security-ref.yml
 delete mode 100644 specification/api/components/security/security.yml
 delete mode 100644 specification/api/components/x-nhsd-apim/prod.env

diff --git a/.gitignore b/.gitignore
index 530cfc0a..07acfc07 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,4 +28,7 @@ dist
 /sandbox-staging
 /specification/api/components/examples
 /specification/api/components/x-nhsd-apim/x-nhsd-apim.yml
+/specification/api/components/security-schemes/security-schemes.yml
+/specification/api/components/security/security.yml
+/specification/api/components/parameters/authorization/authorization.yml
 /scripts/JWT/*.pem
diff --git a/Makefile b/Makefile
index 79eb8edb..a85bbc83 100644
--- a/Makefile
+++ b/Makefile
@@ -46,31 +46,25 @@ publish-oas:
 	npm run publish-oas
 
 set-authorization: guard-APIM_ENV
-	@ AUTHORIZATION=authorization-$$APIM_ENV.yml \
-	envsubst '$${AUTHORIZATION}' \
-	< specification/api/components/parameters/authorization/authorization-template.yml > specification/api/components/parameters/authorization/authorization.yml
+	SPEC_DIR=./specification/api/components/environments
+	COMPONENT_DIR=./specification/api/components/parameters/authorization
+	./scripts/build/substitute_build_env.sh $$COMPONENT_DIR/authorization-template.yml $$SPEC_DIR/$$APIM_ENV.env $$COMPONENT_DIR/authorization.yml
 
-set-target: guard-APIM_ENV
-	@ TARGET=target-$$APIM_ENV.yml \
-	envsubst '$${TARGET}' \
-	< specification/api/components/x-nhsd-apim/target-template.yml > specification/api/components/x-nhsd-apim/target.yml
-
-set-access: guard-APIM_ENV
-	@ ACCESS=access-$$APIM_ENV.yml \
-	envsubst '$${ACCESS}' \
-	< specification/api/components/x-nhsd-apim/access-template.yml > specification/api/components/x-nhsd-apim/access.yml
+set-nhsd-apim: guard-APIM_ENV
+	SPEC_DIR=./specification/api/components/environments
+	COMPONENT_DIR=./specification/api/components/x-nhsd-apim
+	./scripts/build/substitute_build_env.sh $$COMPONENT_DIR/x-nhsd-apim-template.yml $$SPEC_DIR/$$APIM_ENV.env $$COMPONENT_DIR/x-nhsd-apim.yml
 
 set-security: guard-APIM_ENV
-	@ SECURITY=security-$$APIM_ENV.yml \
-	envsubst '$${SECURITY}' \
-	< specification/api/components/security/security-template.yml > specification/api/components/security/security.yml
-	@ SECURITY_SCHEMES=security-schemes-$$APIM_ENV.yml \
-	envsubst '$${SECURITY_SCHEMES}' \
-	< specification/api/components/security-schemes/security-schemes-template.yml > specification/api/components/security-schemes/security-schemes.yml
+	SPEC_DIR=./specification/api/components/environments
+	COMPONENT_DIR=./specification/api/components/security
+	./scripts/build/substitute_build_env.sh $$COMPONENT_DIR/security-template.yml $$SPEC_DIR/$$APIM_ENV.env $$COMPONENT_DIR/security.yml
+	COMPONENT_DIR=./specification/api/components/security-schemes
+	./scripts/build/substitute_build_env.sh $$COMPONENT_DIR/security-schemes-template.yml $$SPEC_DIR/$$APIM_ENV.env $$COMPONENT_DIR/security-schemes.yml
+
 
 construct-spec: guard-APIM_ENV
-	SPEC_DIR=./specification/api/components/x-nhsd-apim
-	./scripts/build/substitute_build_env.sh $$SPEC_DIR/x-nhsd-apim-template.yml $$SPEC_DIR/$$APIM_ENV.env $$SPEC_DIR/x-nhsd-apim.yml
+	$(MAKE) set-nhsd-apim APIM_ENV=$$APIM_ENV
 	$(MAKE) set-authorization APIM_ENV=$$APIM_ENV
 	$(MAKE) set-security APIM_ENV=$$APIM_ENV
 
diff --git a/specification/api/components/security-schemes/security-schemes-ptl.yml b/specification/api/components/environments/common/security-schemes-ptl.yml
similarity index 100%
rename from specification/api/components/security-schemes/security-schemes-ptl.yml
rename to specification/api/components/environments/common/security-schemes-ptl.yml
diff --git a/specification/api/components/x-nhsd-apim/int.env b/specification/api/components/environments/int.env
similarity index 60%
rename from specification/api/components/x-nhsd-apim/int.env
rename to specification/api/components/environments/int.env
index 03fb81fc..147db0d2 100644
--- a/specification/api/components/x-nhsd-apim/int.env
+++ b/specification/api/components/environments/int.env
@@ -1,3 +1,3 @@
 MONITORING_FLAG=false
 TEMPORARY_FLAG=false
-ENV_DIR=./int
+ENV_DIR=../environments/int
diff --git a/specification/api/components/x-nhsd-apim/int/access.yml b/specification/api/components/environments/int/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/int/access.yml
rename to specification/api/components/environments/int/access.yml
diff --git a/specification/api/components/parameters/authorization/authorization-int.yml b/specification/api/components/environments/int/authorization.yml
similarity index 100%
rename from specification/api/components/parameters/authorization/authorization-int.yml
rename to specification/api/components/environments/int/authorization.yml
diff --git a/specification/api/components/x-nhsd-apim/int/rate-limiting.yml b/specification/api/components/environments/int/rate-limiting.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/int/rate-limiting.yml
rename to specification/api/components/environments/int/rate-limiting.yml
diff --git a/specification/api/components/environments/int/security-schemes.yml b/specification/api/components/environments/int/security-schemes.yml
new file mode 100644
index 00000000..a6f42da0
--- /dev/null
+++ b/specification/api/components/environments/int/security-schemes.yml
@@ -0,0 +1 @@
+$ref: '../common/security-schemes-ptl.yml'
diff --git a/specification/api/components/security/security-int.yml b/specification/api/components/environments/int/security.yml
similarity index 100%
rename from specification/api/components/security/security-int.yml
rename to specification/api/components/environments/int/security.yml
diff --git a/specification/api/components/x-nhsd-apim/int/target-attributes.yml b/specification/api/components/environments/int/target-attributes.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/int/target-attributes.yml
rename to specification/api/components/environments/int/target-attributes.yml
diff --git a/specification/api/components/x-nhsd-apim/int/target.yml b/specification/api/components/environments/int/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/int/target.yml
rename to specification/api/components/environments/int/target.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev-pr.env b/specification/api/components/environments/internal-dev-pr.env
similarity index 51%
rename from specification/api/components/x-nhsd-apim/internal-dev-pr.env
rename to specification/api/components/environments/internal-dev-pr.env
index e8820a5e..a9ca9bdd 100644
--- a/specification/api/components/x-nhsd-apim/internal-dev-pr.env
+++ b/specification/api/components/environments/internal-dev-pr.env
@@ -1,3 +1,3 @@
 MONITORING_FLAG=false
 TEMPORARY_FLAG=true
-ENV_DIR=./internal-dev-pr
+ENV_DIR=../environments/internal-dev-pr
diff --git a/specification/api/components/x-nhsd-apim/internal-dev-pr/access.yml b/specification/api/components/environments/internal-dev-pr/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/internal-dev-pr/access.yml
rename to specification/api/components/environments/internal-dev-pr/access.yml
diff --git a/specification/api/components/parameters/authorization/authorization-internal-dev-pr.yml b/specification/api/components/environments/internal-dev-pr/authorization.yml
similarity index 100%
rename from specification/api/components/parameters/authorization/authorization-internal-dev-pr.yml
rename to specification/api/components/environments/internal-dev-pr/authorization.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev-pr/rate-limiting.yml b/specification/api/components/environments/internal-dev-pr/rate-limiting.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/internal-dev-pr/rate-limiting.yml
rename to specification/api/components/environments/internal-dev-pr/rate-limiting.yml
diff --git a/specification/api/components/environments/internal-dev-pr/security-schemes.yml b/specification/api/components/environments/internal-dev-pr/security-schemes.yml
new file mode 100644
index 00000000..a6f42da0
--- /dev/null
+++ b/specification/api/components/environments/internal-dev-pr/security-schemes.yml
@@ -0,0 +1 @@
+$ref: '../common/security-schemes-ptl.yml'
diff --git a/specification/api/components/security/security-internal-dev-pr.yml b/specification/api/components/environments/internal-dev-pr/security.yml
similarity index 100%
rename from specification/api/components/security/security-internal-dev-pr.yml
rename to specification/api/components/environments/internal-dev-pr/security.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev-pr/target-attributes.yml b/specification/api/components/environments/internal-dev-pr/target-attributes.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/internal-dev-pr/target-attributes.yml
rename to specification/api/components/environments/internal-dev-pr/target-attributes.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev-pr/target.yml b/specification/api/components/environments/internal-dev-pr/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/internal-dev-pr/target.yml
rename to specification/api/components/environments/internal-dev-pr/target.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev.env b/specification/api/components/environments/internal-dev.env
similarity index 53%
rename from specification/api/components/x-nhsd-apim/internal-dev.env
rename to specification/api/components/environments/internal-dev.env
index 891efe3a..7f33e0ba 100644
--- a/specification/api/components/x-nhsd-apim/internal-dev.env
+++ b/specification/api/components/environments/internal-dev.env
@@ -1,3 +1,3 @@
 MONITORING_FLAG=false
 TEMPORARY_FLAG=false
-ENV_DIR=./internal-dev
+ENV_DIR=../environments/internal-dev
diff --git a/specification/api/components/x-nhsd-apim/internal-dev/access.yml b/specification/api/components/environments/internal-dev/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/internal-dev/access.yml
rename to specification/api/components/environments/internal-dev/access.yml
diff --git a/specification/api/components/parameters/authorization/authorization-prod.yml b/specification/api/components/environments/internal-dev/authorization.yml
similarity index 100%
rename from specification/api/components/parameters/authorization/authorization-prod.yml
rename to specification/api/components/environments/internal-dev/authorization.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev/rate-limiting.yml b/specification/api/components/environments/internal-dev/rate-limiting.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/internal-dev/rate-limiting.yml
rename to specification/api/components/environments/internal-dev/rate-limiting.yml
diff --git a/specification/api/components/environments/internal-dev/security-schemes.yml b/specification/api/components/environments/internal-dev/security-schemes.yml
new file mode 100644
index 00000000..a6f42da0
--- /dev/null
+++ b/specification/api/components/environments/internal-dev/security-schemes.yml
@@ -0,0 +1 @@
+$ref: '../common/security-schemes-ptl.yml'
diff --git a/specification/api/components/environments/internal-dev/security.yml b/specification/api/components/environments/internal-dev/security.yml
new file mode 100644
index 00000000..c26fe2d7
--- /dev/null
+++ b/specification/api/components/environments/internal-dev/security.yml
@@ -0,0 +1 @@
+app-level3: []
diff --git a/specification/api/components/x-nhsd-apim/internal-dev/target-attributes.yml b/specification/api/components/environments/internal-dev/target-attributes.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/internal-dev/target-attributes.yml
rename to specification/api/components/environments/internal-dev/target-attributes.yml
diff --git a/specification/api/components/x-nhsd-apim/internal-dev/target.yml b/specification/api/components/environments/internal-dev/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/internal-dev/target.yml
rename to specification/api/components/environments/internal-dev/target.yml
diff --git a/specification/api/components/environments/prod.env b/specification/api/components/environments/prod.env
new file mode 100644
index 00000000..a42f92e7
--- /dev/null
+++ b/specification/api/components/environments/prod.env
@@ -0,0 +1,3 @@
+MONITORING_FLAG=true
+TEMPORARY_FLAG=false
+ENV_DIR=../environments/prod
diff --git a/specification/api/components/x-nhsd-apim/prod/access.yml b/specification/api/components/environments/prod/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/prod/access.yml
rename to specification/api/components/environments/prod/access.yml
diff --git a/specification/api/components/parameters/authorization/authorization-ref.yml b/specification/api/components/environments/prod/authorization.yml
similarity index 100%
rename from specification/api/components/parameters/authorization/authorization-ref.yml
rename to specification/api/components/environments/prod/authorization.yml
diff --git a/specification/api/components/x-nhsd-apim/prod/rate-limiting.yml b/specification/api/components/environments/prod/rate-limiting.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/prod/rate-limiting.yml
rename to specification/api/components/environments/prod/rate-limiting.yml
diff --git a/specification/api/components/security-schemes/security-schemes-prod.yml b/specification/api/components/environments/prod/security-schemes.yml
similarity index 100%
rename from specification/api/components/security-schemes/security-schemes-prod.yml
rename to specification/api/components/environments/prod/security-schemes.yml
diff --git a/specification/api/components/environments/prod/security.yml b/specification/api/components/environments/prod/security.yml
new file mode 100644
index 00000000..c26fe2d7
--- /dev/null
+++ b/specification/api/components/environments/prod/security.yml
@@ -0,0 +1 @@
+app-level3: []
diff --git a/specification/api/components/x-nhsd-apim/prod/target-attributes.yml b/specification/api/components/environments/prod/target-attributes.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/prod/target-attributes.yml
rename to specification/api/components/environments/prod/target-attributes.yml
diff --git a/specification/api/components/x-nhsd-apim/prod/target.yml b/specification/api/components/environments/prod/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/prod/target.yml
rename to specification/api/components/environments/prod/target.yml
diff --git a/specification/api/components/x-nhsd-apim/ref.env b/specification/api/components/environments/ref.env
similarity index 60%
rename from specification/api/components/x-nhsd-apim/ref.env
rename to specification/api/components/environments/ref.env
index a2796e9a..5814f7be 100644
--- a/specification/api/components/x-nhsd-apim/ref.env
+++ b/specification/api/components/environments/ref.env
@@ -1,3 +1,3 @@
 MONITORING_FLAG=false
 TEMPORARY_FLAG=false
-ENV_DIR=./ref
+ENV_DIR=../environments/ref
diff --git a/specification/api/components/x-nhsd-apim/ref/access.yml b/specification/api/components/environments/ref/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/ref/access.yml
rename to specification/api/components/environments/ref/access.yml
diff --git a/specification/api/components/parameters/authorization/authorization-internal-dev.yml b/specification/api/components/environments/ref/authorization.yml
similarity index 93%
rename from specification/api/components/parameters/authorization/authorization-internal-dev.yml
rename to specification/api/components/environments/ref/authorization.yml
index de566bd1..c4e9225d 100644
--- a/specification/api/components/parameters/authorization/authorization-internal-dev.yml
+++ b/specification/api/components/environments/ref/authorization.yml
@@ -2,7 +2,7 @@ name: Authorization
 in: header
 description: |-
   An OAuth 2.0 bearer token. Required in integration and production environments.
-required: false
+required: true
 schema:
   type: string
   pattern: ^Bearer [[:ascii:]]+$
diff --git a/specification/api/components/x-nhsd-apim/ref/rate-limiting.yml b/specification/api/components/environments/ref/rate-limiting.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/ref/rate-limiting.yml
rename to specification/api/components/environments/ref/rate-limiting.yml
diff --git a/specification/api/components/environments/ref/security-schemes.yml b/specification/api/components/environments/ref/security-schemes.yml
new file mode 100644
index 00000000..a6f42da0
--- /dev/null
+++ b/specification/api/components/environments/ref/security-schemes.yml
@@ -0,0 +1 @@
+$ref: '../common/security-schemes-ptl.yml'
diff --git a/specification/api/components/environments/ref/security.yml b/specification/api/components/environments/ref/security.yml
new file mode 100644
index 00000000..c26fe2d7
--- /dev/null
+++ b/specification/api/components/environments/ref/security.yml
@@ -0,0 +1 @@
+app-level3: []
diff --git a/specification/api/components/x-nhsd-apim/ref/target-attributes.yml b/specification/api/components/environments/ref/target-attributes.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/ref/target-attributes.yml
rename to specification/api/components/environments/ref/target-attributes.yml
diff --git a/specification/api/components/x-nhsd-apim/ref/target.yml b/specification/api/components/environments/ref/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/ref/target.yml
rename to specification/api/components/environments/ref/target.yml
diff --git a/specification/api/components/x-nhsd-apim/sandbox.env b/specification/api/components/environments/sandbox.env
similarity index 57%
rename from specification/api/components/x-nhsd-apim/sandbox.env
rename to specification/api/components/environments/sandbox.env
index d4a1435e..21db9402 100644
--- a/specification/api/components/x-nhsd-apim/sandbox.env
+++ b/specification/api/components/environments/sandbox.env
@@ -1,3 +1,3 @@
 MONITORING_FLAG=false
 TEMPORARY_FLAG=false
-ENV_DIR=./sandbox
+ENV_DIR=../environments/sandbox
diff --git a/specification/api/components/x-nhsd-apim/sandbox/access.yml b/specification/api/components/environments/sandbox/access.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/sandbox/access.yml
rename to specification/api/components/environments/sandbox/access.yml
diff --git a/specification/api/components/parameters/authorization/authorization-sandbox.yml b/specification/api/components/environments/sandbox/authorization.yml
similarity index 93%
rename from specification/api/components/parameters/authorization/authorization-sandbox.yml
rename to specification/api/components/environments/sandbox/authorization.yml
index de566bd1..c4e9225d 100644
--- a/specification/api/components/parameters/authorization/authorization-sandbox.yml
+++ b/specification/api/components/environments/sandbox/authorization.yml
@@ -2,7 +2,7 @@ name: Authorization
 in: header
 description: |-
   An OAuth 2.0 bearer token. Required in integration and production environments.
-required: false
+required: true
 schema:
   type: string
   pattern: ^Bearer [[:ascii:]]+$
diff --git a/specification/api/components/x-nhsd-apim/sandbox/rate-limiting.yml b/specification/api/components/environments/sandbox/rate-limiting.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/sandbox/rate-limiting.yml
rename to specification/api/components/environments/sandbox/rate-limiting.yml
diff --git a/specification/api/components/environments/sandbox/security-schemes.yml b/specification/api/components/environments/sandbox/security-schemes.yml
new file mode 100644
index 00000000..a6f42da0
--- /dev/null
+++ b/specification/api/components/environments/sandbox/security-schemes.yml
@@ -0,0 +1 @@
+$ref: '../common/security-schemes-ptl.yml'
diff --git a/specification/api/components/security/security-sandbox.yml b/specification/api/components/environments/sandbox/security.yml
similarity index 100%
rename from specification/api/components/security/security-sandbox.yml
rename to specification/api/components/environments/sandbox/security.yml
diff --git a/specification/api/components/x-nhsd-apim/sandbox/target-attributes.yml b/specification/api/components/environments/sandbox/target-attributes.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/sandbox/target-attributes.yml
rename to specification/api/components/environments/sandbox/target-attributes.yml
diff --git a/specification/api/components/x-nhsd-apim/sandbox/target.yml b/specification/api/components/environments/sandbox/target.yml
similarity index 100%
rename from specification/api/components/x-nhsd-apim/sandbox/target.yml
rename to specification/api/components/environments/sandbox/target.yml
diff --git a/specification/api/components/parameters/authorization/authorization-template.yml b/specification/api/components/parameters/authorization/authorization-template.yml
index dcb94c5f..420a173d 100644
--- a/specification/api/components/parameters/authorization/authorization-template.yml
+++ b/specification/api/components/parameters/authorization/authorization-template.yml
@@ -1 +1 @@
-$ref: $AUTHORIZATION
+$ref: ../$ENV_DIR/authorization.yml
diff --git a/specification/api/components/parameters/authorization/authorization.yml b/specification/api/components/parameters/authorization/authorization.yml
deleted file mode 100644
index 1dd82fdc..00000000
--- a/specification/api/components/parameters/authorization/authorization.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: authorization-prod.yml
diff --git a/specification/api/components/security-schemes/security-schemes-int.yml b/specification/api/components/security-schemes/security-schemes-int.yml
deleted file mode 100644
index 80a446d6..00000000
--- a/specification/api/components/security-schemes/security-schemes-int.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: './security-schemes-ptl.yml'
diff --git a/specification/api/components/security-schemes/security-schemes-internal-dev-pr.yml b/specification/api/components/security-schemes/security-schemes-internal-dev-pr.yml
deleted file mode 100644
index 80a446d6..00000000
--- a/specification/api/components/security-schemes/security-schemes-internal-dev-pr.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: './security-schemes-ptl.yml'
diff --git a/specification/api/components/security-schemes/security-schemes-internal-dev.yml b/specification/api/components/security-schemes/security-schemes-internal-dev.yml
deleted file mode 100644
index 80a446d6..00000000
--- a/specification/api/components/security-schemes/security-schemes-internal-dev.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: './security-schemes-ptl.yml'
diff --git a/specification/api/components/security-schemes/security-schemes-ref.yml b/specification/api/components/security-schemes/security-schemes-ref.yml
deleted file mode 100644
index 80a446d6..00000000
--- a/specification/api/components/security-schemes/security-schemes-ref.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: './security-schemes-ptl.yml'
diff --git a/specification/api/components/security-schemes/security-schemes-sandbox.yml b/specification/api/components/security-schemes/security-schemes-sandbox.yml
deleted file mode 100644
index 80a446d6..00000000
--- a/specification/api/components/security-schemes/security-schemes-sandbox.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: './security-schemes-ptl.yml'
diff --git a/specification/api/components/security-schemes/security-schemes-template.yml b/specification/api/components/security-schemes/security-schemes-template.yml
index f15a14a3..8a25f7d8 100644
--- a/specification/api/components/security-schemes/security-schemes-template.yml
+++ b/specification/api/components/security-schemes/security-schemes-template.yml
@@ -1 +1 @@
-$ref: $SECURITY_SCHEMES
+$ref: $ENV_DIR/security-schemes.yml
diff --git a/specification/api/components/security-schemes/security-schemes.yml b/specification/api/components/security-schemes/security-schemes.yml
deleted file mode 100644
index 78a3ea0e..00000000
--- a/specification/api/components/security-schemes/security-schemes.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: security-schemes-prod.yml
diff --git a/specification/api/components/security/security-internal-dev.yml b/specification/api/components/security/security-internal-dev.yml
deleted file mode 100644
index 878d7f27..00000000
--- a/specification/api/components/security/security-internal-dev.yml
+++ /dev/null
@@ -1 +0,0 @@
-app-level3: [ ]
diff --git a/specification/api/components/security/security-prod.yml b/specification/api/components/security/security-prod.yml
deleted file mode 100644
index 878d7f27..00000000
--- a/specification/api/components/security/security-prod.yml
+++ /dev/null
@@ -1 +0,0 @@
-app-level3: [ ]
diff --git a/specification/api/components/security/security-ref.yml b/specification/api/components/security/security-ref.yml
deleted file mode 100644
index 878d7f27..00000000
--- a/specification/api/components/security/security-ref.yml
+++ /dev/null
@@ -1 +0,0 @@
-app-level3: [ ]
diff --git a/specification/api/components/security/security-template.yml b/specification/api/components/security/security-template.yml
index ffd1d328..58aea08e 100644
--- a/specification/api/components/security/security-template.yml
+++ b/specification/api/components/security/security-template.yml
@@ -1 +1 @@
-$ref: $SECURITY
+$ref: $ENV_DIR/security.yml
diff --git a/specification/api/components/security/security.yml b/specification/api/components/security/security.yml
deleted file mode 100644
index 393524ce..00000000
--- a/specification/api/components/security/security.yml
+++ /dev/null
@@ -1 +0,0 @@
-$ref: security-prod.yml
diff --git a/specification/api/components/x-nhsd-apim/prod.env b/specification/api/components/x-nhsd-apim/prod.env
deleted file mode 100644
index a05318ea..00000000
--- a/specification/api/components/x-nhsd-apim/prod.env
+++ /dev/null
@@ -1,3 +0,0 @@
-MONITORING_FLAG=false
-TEMPORARY_FLAG=false
-ENV_DIR=./prod

From 9a5e24ef9c50045d432ecd2da725620906076f01 Mon Sep 17 00:00:00 2001
From: David Wass <david.wass2@nhs.net>
Date: Wed, 10 Dec 2025 16:28:54 +0000
Subject: [PATCH 3/4] Update monitoring to true for all envs except PRs

---
 specification/api/components/environments/int.env          | 2 +-
 specification/api/components/environments/internal-dev.env | 2 +-
 specification/api/components/environments/ref.env          | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/specification/api/components/environments/int.env b/specification/api/components/environments/int.env
index 147db0d2..cfea3938 100644
--- a/specification/api/components/environments/int.env
+++ b/specification/api/components/environments/int.env
@@ -1,3 +1,3 @@
-MONITORING_FLAG=false
+MONITORING_FLAG=true
 TEMPORARY_FLAG=false
 ENV_DIR=../environments/int
diff --git a/specification/api/components/environments/internal-dev.env b/specification/api/components/environments/internal-dev.env
index 7f33e0ba..2fed2ab0 100644
--- a/specification/api/components/environments/internal-dev.env
+++ b/specification/api/components/environments/internal-dev.env
@@ -1,3 +1,3 @@
-MONITORING_FLAG=false
+MONITORING_FLAG=true
 TEMPORARY_FLAG=false
 ENV_DIR=../environments/internal-dev
diff --git a/specification/api/components/environments/ref.env b/specification/api/components/environments/ref.env
index 5814f7be..0c62c810 100644
--- a/specification/api/components/environments/ref.env
+++ b/specification/api/components/environments/ref.env
@@ -1,3 +1,3 @@
-MONITORING_FLAG=false
+MONITORING_FLAG=true
 TEMPORARY_FLAG=false
 ENV_DIR=../environments/ref

From 1dfc332422efa7877c5160eed589c3c799bc835c Mon Sep 17 00:00:00 2001
From: David Wass <david.wass2@nhs.net>
Date: Wed, 10 Dec 2025 16:40:09 +0000
Subject: [PATCH 4/4] sandbox authorization optional

---
 .../api/components/environments/sandbox/authorization.yml       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specification/api/components/environments/sandbox/authorization.yml b/specification/api/components/environments/sandbox/authorization.yml
index c4e9225d..de566bd1 100644
--- a/specification/api/components/environments/sandbox/authorization.yml
+++ b/specification/api/components/environments/sandbox/authorization.yml
@@ -2,7 +2,7 @@ name: Authorization
 in: header
 description: |-
   An OAuth 2.0 bearer token. Required in integration and production environments.
-required: true
+required: false
 schema:
   type: string
   pattern: ^Bearer [[:ascii:]]+$