Skip to main content

Web application via server

Warning You must submit data for all of these headers.

You should check that your chosen technology stack supports collecting data for all required headers, for example, Gov-Client-Public-IP and Gov-Client-Public-Port.

Where multiple services manage your intermediary servers, headers must contain data from all services.

  1. Gov-Client-Connection-Method

    For your connection method, submit this header and value with all requests:

    Gov-Client-Connection-Method: WEB_APP_VIA_SERVER

  2. Gov-Client-Browser-JS-User-Agent

    JavaScript-reported user agent string from the originating device.

    Pass the value as reported by the browser, usually in this format:
    <product> / <product-version> (<system-information>) <platform> (<platform-details>) <extensions>

    Example

    Gov-Client-Browser-JS-User-Agent: Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405

  3. Gov-Client-Device-ID

    An identifier unique to the originating device.

    • You need to generate a universally unique identifier (UUID), also known as a globally unique identifier (GUID), to use as a device ID
    • This should be generated by an application and persistently stored on the device. You can store the device ID in a hidden file, the Windows registry, or in a cookie.
    • The identifier should not expire
    • If your end user deletes the device ID, you need to generate a new one

    Example

    Gov-Client-Device-ID: beec798b-b366-47fa-b1f8-92cede14a1ce

  4. Gov-Client-Multi-Factor

    A list of key-value data structures containing details of the multi-factor authentication (MFA) statuses related to the API call.

    • This relates to users accessing your software, not users granting authority for your software to access their data
    • If you authenticate with username and password only, you will not be able to collect a value. You need to check what to do about missing data.
    • Every key and value must be percent encoded (opens in a new tab). Do not percent encode the separators (equal signs, ampersands and commas).

    Fields for each key-value data structure

    type is a tag describing the MFA method being used. The possible values are:

    • TOTP the MFA was performed by accepting a time-based one-time password code
    • AUTH_CODE the MFA was performed by sending an authorisation code to the user in some out-of-band channel, for example, by email or by SMS
    • OTHER a different MFA method was used than the available values

    timestamp is a UTC timestamp recording the time of the last successful prompt for this factor. As a minimum, use this format yyyy-MM-ddThh:mmZ. You can include seconds and milliseconds.

    unique-reference identifies a single factor. For example, a salted-and-hashed phone number used for SMS, or an identifier linked to a TOTP secret, but not the secret itself. Use the same hashing function consistently so that this can be recognised across API calls.

    Example

    Gov-Client-Multi-Factor: type=AUTH_CODE&timestamp=2021-11-21T13%3A23Z&unique-reference=fc4b5fd6816f75a7c81fc8eaa9499d6a299bd803397166e8c4cf9280b801d62c,type=TOTP&timestamp=2021-11-21T13%3A20Z&unique-reference=0283da60063abfb3a87f1aed845d17fe2d9ba8c780b478dc4ae048f5ee97a6d5

  5. Gov-Client-Public-IP

    The public IPv4 or IPv6 address from which the originating device makes the request.

    If the connection between client and server is over a private network, you will not be able to collect a value. You need to check what to do about missing data.

    You should check that your chosen technology stack supports the collection of this value. Some popular load balancers do not.

    Examples

    Gov-Client-Public-IP: 198.51.100.0
    Gov-Client-Public-IP: ABCD:EF01:2345:6789:ABCD:EF01:2345:6789

  6. Gov-Client-Public-IP-Timestamp

    A timestamp to show when Gov-Client-Public-IP is collected.

    • Collect the timestamp at the same time your application collects the client’s public IP address. This is usually when the backend server receives the request from the client. It could be at the Web Application Firewall (WAF), load balancer, reverse proxy or the server process itself.
    • If the timestamp is not in UTC zero time offset, you’ll need to convert it
    • Submit a UTC timestamp in the format yyyy-MM-ddThh:mm:ss.sssZ where Z designates zero time offset
    • You must include T and use the 24 hour format
    • You must include seconds and milliseconds, including trailing zeros

    Example

    Gov-Client-Public-IP-Timestamp: 2020-09-21T14:30:05.123Z

  7. Gov-Client-Public-Port

    The public TCP port used by the originating device when initiating the request.

    You should check that your chosen technology stack supports the collection of this value. Some popular load balancers do not.

    • This must not be a server port, for example 80 for http connections and 443 for https connections
    • The valid range is between 1 and 65535
    • If the connection between client and server is over a private network, you will not be able to collect a value. You need to check what to do about missing data.

    Example

    Gov-Client-Public-Port: 12345

  8. Gov-Client-Screens

    Information about the originating device’s screens.

    These fields should be submitted as a list of key-value data structures:

    width is the reported width of the screen in pixels

    height is the reported height of the screen in pixels

    scaling-factor is the reported scaling factor of the screen. For example, high-pixel density screens might have a scaling factor of 2, whereas standard definition screens might have a scaling factor of 1.

    colour-depth is the colour depth of the screen in bits

    Example

    Gov-Client-Screens: width=1920&height=1080&scaling-factor=1&colour-depth=16,width=3000&height=2000&scaling-factor=1.25&colour-depth=16

  9. Gov-Client-Timezone

    The local timezone of the originating device. You need to submit a recognised timezone in UTC (Coordinated Universal Time) format, expressed as UTC±<hh>:<mm>

    Examples

    Gov-Client-Timezone: UTC+00:00
    Gov-Client-Timezone: UTC+01:00
    Gov-Client-Timezone: UTC-01:15

  10. Gov-Client-User-IDs

    A key-value data structure containing user identifiers.

    • The keys should indicate accounts the user holds
    • Additional fields need to contain the user’s identifiers. This includes the identifier that the user signs into the application with, for example username, email or phone number. If there is an internal identifier, you should include it too.
    • Every key and value must be percent encoded (opens in a new tab). Do not percent encode separators (equal signs and ampersands).

    Example

    Gov-Client-User-IDs: my-application=alice123

  11. Gov-Client-Window-Size

    The number of pixels of the window on the originating device.

    This should be displayed as a key-value data structure with width and height fields.

    Example

    Gov-Client-Window-Size: width=1256&height=803

  12. Gov-Vendor-Forwarded

    A list that details hops over the internet between services that terminate Transport Layer Security (TLS).

    • For each hop over the internet, a key-value data structure with a by and for field must be appended to the list
    • The by field must be the public IP address that the server received the request on. For the last hop, this is the public IP address of the server and value of Gov-Vendor-Public-IP.
    • The for field must be the public IP address of the request sender. For the first hop, this is the public IP address of the client and value of Gov-Client-Public-IP. For subsequent hops, it is the public IP address of the intermediate server.
    • Each key and value must be percent encoded (opens in a new tab). Do not percent encode separators (equal signs, ampersands and commas).
    • Do not include hops within a private network

    Example 1

    A simple client and server request.

    1. A web client with the public IP address 198.51.100.0 makes a request to a vendor server
    2. The vendor server with the public IP address 203.0.113.6 receives the request and forwards it to HMRC

    The header should look like this:

    Gov-Vendor-Forwarded: by=203.0.113.6&for=198.51.100.0

    Example 2

    The request passes through a Web Application Firewall (WAF) and multiple servers belonging to the vendor.

    Make sure by and for fields are added for every hop within the request.

    1. A web client, on public IP address 198.51.100.0, makes a request to a WAF
    2. The WAF, on public IP address 2001:0db8:85a3:0000:0000:8a2e:0370:7334, receives the request and forwards it to vendor server 1
    3. Vendor server 1, on public IP address 203.0.113.6, receives the request and forwards it to vendor server 2
    4. Vendor server 2, on public IP address 176.30.57.118, receives the request and forwards it to HMRC

    The header should look like this:

    Gov-Vendor-Forwarded: by=2001%3A0db8%3A85a3%3A0000%3A0000%3A8a2e%3A0370%3A7334&for=198.51.100.0,by=203.0.113.6&for=2001%3A0db8%3A85a3%3A0000%3A0000%3A8a2e%3A0370%3A7334,by=176.30.57.118&for=203.0.113.6

  13. Gov-Vendor-License-IDs

    A key-value data structure of hashed license keys relating to the vendor software initiating the API request on the originating device.

    • Use this format:
      <software-name>=<hashed-license-value>&<software-name-2>=<hashed-license-value-2>& …
    • To keep consistency in the values submitted, use the same hashing function
    • Every key and value must be percent encoded (opens in a new tab). Do not percent encode separators (equal signs and ampersands).
    • If there are no licenses on the originating device, you will not be able to collect a value. You need to check what to do about missing data.

    Example

    Gov-Vendor-License-IDs: my-licensed-software=8D7963490527D33716835EE7C195516D5E562E03B224E9B359836466EE40CDE1

  14. Gov-Vendor-Product-Name

    The name of the product marketed to end users.

    • The value must be percent encoded (opens in a new tab)
    • If your application is built for internal use only, submit your company name
    • If you’re using a white-labelled product, submit your company name

    Examples

    Gov-Vendor-Product-Name: Product%20Name
    Gov-Vendor-Product-Name: Company%20Name

  15. Gov-Vendor-Public-IP

    The public IP address of the servers the originating device sent their requests to.

    • This could be an IP address of a Web Application Firewall (WAF), a DDoS Protection Service, or a load balancer that the vendor’s DNS record resolves to
    • If the connection between client and server is over a private network, you will not be able to collect a public IP address. You need to check what to do about missing data.

    Example

    Gov-Vendor-Public-IP: 203.0.113.6

  16. Gov-Vendor-Version

    A key-value data structure of versions of your software involved in handling a request.

    • Use this format:
      <software-name>=<version-number>&<software-name-2>=<version-number-2>& …
    • Every key and value must be percent encoded (opens in a new tab). Do not percent encode separators (equal signs and ampersands).

    Example

    Gov-Vendor-Version: my-web-app=2.2.2