NPA-6550: docs for proxygen setup by ehallam · Pull Request #125 · NHSDigital/im1-pfs-auth

ehallam · 2026-04-23T11:01:34Z

Pull Request

🧾 Ticket Link

https://nhsd-jira.digital.nhs.uk/browse/NPA-6550

📄 Description/Summary of Changes

🧪 Developer Testing Carried Out

📋 PR Principles

Keep PRs Small and Focused: Ensure the PR addresses a single task or feature to make it easier to review.
Multiple PRs for one Ticket: When splitting work into multiple PRs, clearly describe what this PR addresses and outline the remaining work to complete the ticket.
Ensure Tests Are Included: Add or update unit, integration, or end-to-end tests to cover the changes made.
Follow Coding Standards: Ensure the code adheres to the team's coding guidelines and best practices.
Resolve Comments Promptly: If you raise a comment, ensure you follow up and resolve it before approving the PR to maintain clarity and ensure comments are addressed.
Foster Learning: PR reviews are an opportunity to share knowledge, provide constructive feedback, and encourage a collaborative environment.

🏷️ Naming Conventions Reminder

Please ensure the following naming conventions are followed:

PR title follows the format: NPA-XXXX: <short-description>
Branch name follows the convention: <type>/NPA-XXXX/<short-description>
Commit messages follow the template: NPA-XXXX: <short-description>

Copilot

Pull request overview

Adds a developer guide describing how to set up Proxygen (key generation, ServiceNow request, proxygen-cli install/config, and basic deploy/get commands).

Changes:

Added a new developer guide covering Proxygen setup steps and required configuration files.
Documented proxygen-cli installation and example commands for deploying/retrieving specs.
Included guidance on Key ID (KID) structure and how to request a Proxygen API/client.

Comments suppressed due to low confidence (1)

docs/developer-guides/Rotating_proxygen_keys.md:85

The section "Deploying the spec via a pipeline" is currently just a heading with no content. If this is intentionally out of scope for this PR, consider removing the heading; otherwise add the missing steps (or mark it explicitly as TODO with a link) so readers aren’t left at a dead end.

## Deploying the spec via a pipeline

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-23T11:04:29Z

+This enforces a 12-month expiry for all public keys (The date should be expiry date of the Public Key)
+```
+
+[These docs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#step-2-generate-a-key-pair) walkthrough how to generate the key pair. Once you've created your JWKS file called YOUR_KID.json you can move onto creating the proxygen deployment


Grammar: "walkthrough" is used as a verb here; consider "walks through" or "walk through". Also "move onto" should be "move on to". These small fixes make the instructions read more cleanly.

Suggested change

[These docs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#step-2-generate-a-key-pair) walkthrough how to generate the key pair. Once you've created your JWKS file called YOUR_KID.json you can move onto creating the proxygen deployment

[These docs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#step-2-generate-a-key-pair) walk through how to generate the key pair. Once you've created your JWKS file called YOUR_KID.json you can move on to creating the proxygen deployment

Copilot · 2026-04-23T11:04:30Z

+base_url: https://identity.{ptl | prod}.api.platform.nhs.uk/realms/api-producers
+client_id: {Client ID}


The base_url placeholder includes spaces and a | inside braces ({ptl | prod}), which makes it easy to accidentally copy/paste an invalid URL into credentials.yaml. Consider providing two explicit example URLs (one for PTL and one for PROD), or use a placeholder format without spaces/symbols that would break the URL.

Copilot · 2026-04-23T11:04:30Z

+endpoint_url: https://proxygen.{ptl | prod}.api.platform.nhs.uk
+spec_output_format: yaml


Same issue as base_url: endpoint_url uses a {ptl | prod} placeholder that will produce an invalid URL if copied verbatim. Provide explicit PTL/PROD examples or a safer placeholder format.

Copilot · 2026-04-23T11:04:31Z

+
+Once you have this key pair, you can raise a [service now request](https://nhsdigitallive.service-now.com/csm?id=sc_cat_item&sys_id=b5e2c7ee9777a610dd80f2df9153af87&sysparm_category=63f4716697731e90dd80f2df9153affe) with the information you used to create the key pair to "Create an API on Proxygen".
+
+Once APIM have done this, they will provide you with a client ID in the service now request, e.g. im1-pfs-auth-client which you will need to setup machine access to the API.


"setup" is used as a verb here; in prose it should typically be "set up" (verb) vs "setup" (noun/adjective). Aligning the phrasing helps readability.

Suggested change

Once APIM have done this, they will provide you with a client ID in the service now request, e.g. im1-pfs-auth-client which you will need to setup machine access to the API.

Once APIM have done this, they will provide you with a client ID in the service now request, e.g. im1-pfs-auth-client which you will need to set up machine access to the API.

Copilot · 2026-04-23T11:04:31Z

+
+### .proxygen config files
+
+To fully setup machine access, you will need a credentials.yaml and settings.yaml file inside of ~/.proxygen


Same "set up" vs "setup" issue: "To fully setup machine access" reads as a verb phrase, so "set up" would be clearer.

Suggested change

To fully setup machine access, you will need a credentials.yaml and settings.yaml file inside of ~/.proxygen

To fully set up machine access, you will need a credentials.yaml and settings.yaml file inside of ~/.proxygen

Copilot · 2026-04-23T11:04:31Z

+From the [APIM slack message](https://nhsuk.slack.com/archives/C016JRWN6AY/p1773828313442569):
+```Follow the new Key ID (KID) structure:
+
+YYYY-mm-dd-PTL-<<api-name>>
+YYYY-mm-dd-Prod-<<api-name>>
+This enforces a 12-month expiry for all public keys (The date should be expiry date of the Public Key)
+```


The fenced code block for the Slack quote is malformed (the opening fence includes text: "Follow..."). This will render incorrectly in Markdown. Put the opening on its own line (optionally with a language like text) and move the quote content onto the next line.

Copilot · 2026-04-23T11:04:31Z

+
+## Generating a key pair
+
+You'll need to generate a public and private key pair before raising a service now request to create the proxygen API


"service now" should be the product name "ServiceNow" (one word, proper capitalization) and this sentence is missing terminal punctuation. Adjusting this improves clarity and searchability.

Suggested change

You'll need to generate a public and private key pair before raising a service now request to create the proxygen API

You'll need to generate a public and private key pair before raising a ServiceNow request to create the proxygen API.

Copilot · 2026-04-23T11:04:32Z

@@ -0,0 +1,84 @@
+# Setting up Proxygen


The document title is "Setting up Proxygen" but the file is named Rotating_proxygen_keys.md. This mismatch makes the doc harder to discover and link correctly. Consider renaming the file (or adjusting the title) so the filename reflects the actual content.

Suggested change

# Setting up Proxygen

# Rotating Proxygen keys

Copilot · 2026-04-23T11:04:32Z

+You're looking for one that looks like `/Users/elliot/Library/Python/3.13/bin/proxygen`
+
+Once you have this path, you can add it to your .zshrc with `export PATH="$PATH:/Users/elliot/Library/Python/3.13/bin/"`


This example uses a specific developer machine path (/Users/elliot/...) and a specific Python version. That’s likely to confuse others and will go stale. Prefer using $HOME/~ and/or a more general way to locate the user-base bin directory so the instructions work across machines.

Suggested change

You're looking for one that looks like `/Users/elliot/Library/Python/3.13/bin/proxygen`

Once you have this path, you can add it to your .zshrc with `export PATH="$PATH:/Users/elliot/Library/Python/3.13/bin/"`

You're looking for one that looks like `~/Library/Python/.../bin/proxygen`

Once you have this path, add the directory containing it to your `.zshrc`, for example with `export PATH="$PATH:$(dirname "$(find ~ -name "proxygen" 2>/dev/null | head -n 1)")"`

davesmallnhs · 2026-04-27T10:52:46Z

+
+YYYY-mm-dd-PTL-<<api-name>>
+YYYY-mm-dd-Prod-<<api-name>>
+This enforces a 12-month expiry for all public keys (The date should be expiry date of the Public Key)


Worth saying YYYY-mm-dd should be the expiry date, not today's date. This confused me, from what's written

ehallam added 2 commits April 23, 2026 11:58

NPA-6550: added proxygen key rotation docs

ab44534

NPA-6550: slight docs change

a54eeb7

Copilot AI review requested due to automatic review settings April 23, 2026 11:01

Copilot started reviewing on behalf of ehallam April 23, 2026 11:01 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

NPA-6550: fix docs

c35b1ac

davesmallnhs reviewed Apr 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

NPA-6550: docs for proxygen setup#125

NPA-6550: docs for proxygen setup#125
ehallam wants to merge 3 commits intomainfrom
task/NPA-6550/docs-for-proxygen-setup

ehallam commented Apr 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

davesmallnhs Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	[These docs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#step-2-generate-a-key-pair) walkthrough how to generate the key pair. Once you've created your JWKS file called YOUR_KID.json you can move onto creating the proxygen deployment
	[These docs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#step-2-generate-a-key-pair) walk through how to generate the key pair. Once you've created your JWKS file called YOUR_KID.json you can move on to creating the proxygen deployment

		base_url: https://identity.{ptl \| prod}.api.platform.nhs.uk/realms/api-producers
		client_id: {Client ID}

		endpoint_url: https://proxygen.{ptl \| prod}.api.platform.nhs.uk
		spec_output_format: yaml


		Once you have this key pair, you can raise a [service now request](https://nhsdigitallive.service-now.com/csm?id=sc_cat_item&sys_id=b5e2c7ee9777a610dd80f2df9153af87&sysparm_category=63f4716697731e90dd80f2df9153affe) with the information you used to create the key pair to "Create an API on Proxygen".

		Once APIM have done this, they will provide you with a client ID in the service now request, e.g. im1-pfs-auth-client which you will need to setup machine access to the API.


		### .proxygen config files

		To fully setup machine access, you will need a credentials.yaml and settings.yaml file inside of ~/.proxygen

	To fully setup machine access, you will need a credentials.yaml and settings.yaml file inside of ~/.proxygen
	To fully set up machine access, you will need a credentials.yaml and settings.yaml file inside of ~/.proxygen


		## Generating a key pair

		You'll need to generate a public and private key pair before raising a service now request to create the proxygen API

		You're looking for one that looks like `/Users/elliot/Library/Python/3.13/bin/proxygen`

		Once you have this path, you can add it to your .zshrc with `export PATH="$PATH:/Users/elliot/Library/Python/3.13/bin/"`

Conversation

ehallam commented Apr 23, 2026

Pull Request

🧾 Ticket Link

📄 Description/Summary of Changes

🧪 Developer Testing Carried Out

📋 PR Principles

🏷️ Naming Conventions Reminder

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

davesmallnhs Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants