Skip to main content

Other 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: OTHER_VIA_SERVER

  2. 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

  3. Gov-Client-Local-IPs

    A list of all local IPv4 and IPv6 addresses available to the originating device.

    • Values must be collected immediately before each request is sent by the client to the backend server
    • Every IPv6 value in the list must be percent encoded (opens in a new tab). Do not percent encode separators (commas).

    Examples

    Gov-Client-Local-IPs: fc00%3A%3A,10.1.2.3
    Gov-Client-Local-IPs: 10.1.2.3,10.3.4.2

  4. Gov-Client-Local-IPs-Timestamp

    A timestamp to show when Gov-Client-Local-IPs is collected.

    • Collect the timestamp immediately before the client makes the request to the backend server that triggers a request to the API
    • The value must not be altered before being sent to the API
    • 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-Local-IPs-Timestamp: 2020-09-21T14:30:05.123Z

  5. Gov-Client-MAC-Addresses

    The list of MAC addresses available on the originating device.

    Example

    Gov-Client-MAC-Addresses: ea%3A43%3A1a%3A5d%3A21%3A45,10%3A12%3Acc%3Afa%3Aaa%3A32

  6. 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

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

  8. 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

  9. 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

  10. 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

  11. Gov-Client-User-Agent

    Identifies the operating system and device.

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

    • os-family is the operating system family, for example Windows or MacOS
    • os-version is the operating system version, for example 10 or 10.15.7
    • device-manufacturer is the manufacturer of the device, for example Dell or Apple
    • device-model is the model of the device, for example XPS13 or MacBookPro15,2

    Every key and value must be percent encoded (opens in a new tab).

    Example

    Gov-Client-User-Agent: os-family=Windows&os-version=Server%202012&device-manufacturer=Dell%20Inc.&device-model=OptiPlex%20980

  12. Gov-Client-User-IDs

    A key-value data structure containing user identifiers.

    • The keys should indicate accounts the user holds
    • The os field should contain the identifier of the user signed in on the originating device
    • 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: os=alice&my-application=alice123

  13. 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
    • 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. 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

  14. 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

  15. 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

  16. 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

  17. 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-frontend-app=2.2.2&my-serverside-code=v3.8