<!--
{
  "documentType" : "article",
  "framework" : "ExposureNotification",
  "identifier" : "/documentation/ExposureNotification/changing-configuration-values-using-the-server-to-server-api",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Changing Configuration Values Using the Server‑to‑Server API"
}
-->

# Changing Configuration Values Using the Server‑to‑Server API

Update Exposure Notifications configuration values from a Public Health Authority’s server.

## Discussion

The Exposure Notifications feature reads configuration values to customize behavior for each region based on values provided by that region’s Public Health Authority (PHA). PHAs can push changes to these configuration values from their servers using the Exposure Notifications server-to-server API. A PHA might use the server-to-server API, for example, to automate changes under certain conditions, such as changing the polling interval when experiencing unusually high activity, or providing a configuration portal hosted on their own servers.

Exposure Notifications server-to-server API is located at the following URL:

```shell
https://gateway.icloud.com/enservice/v2/update/app/config
```

This API expects a POST request with a content-type of `application/json.` Requests must include both of the custom headers listed below to authenticate the request. The server rejects requests that the API can’t authenticate, and doesn’t make any changes to the existing configuration values.

- `X-Apple-verification-data`: The name of the Health Authority submitting the request as a Base64-encoded UTF-8 string.
- `X-Apple-signature`: A digital signature of the string in the `X-Apple-verification-data` header, signed with the private key that corresponds to the most recent public key provided to Apple.

The body of the POST request contains a JSON dictionary that uses the following keys:

- `appBundleID`: Identifier for the client app to which these configuration changes apply. This field isn’t needed when making changes that only apply to Exposure Notifications Express.
- `countryCode`: The two-letter ISO country code that corresponds to the region for which these configuration changes apply.
- `state`: The two-letter subdivision code that corresponds to the state, province, or other administrative division for which these configuration changes apply, if needed.
- `publicKeyVersion`: An integer that represents the version of the PHA’s public key, for use when authenticating requests using the custom headers, listed above.
- `config`: A JSON dictionary used to specify new configuration values. For a list of available keys and their expected values, see [Configuring Exposure Notifications](/documentation/ExposureNotification/configuring-exposure-notifications).

This API responds with an HTTP response code, but won’t send a response body or any custom headers. If the API can make the requested changes, the API returns an HTTP `200` response code. If the API can’t change the values, it returns one of the following codes:

- `400` (Invalid Payload): Can’t validate the JSON in the body of the request. This could be because the JSON is invalid, missing required keys, or includes unrecognized keys.
- `401` (Unauthorized): Can’t validate the PHA’s digital signature contained in the custom headers.
- `404` (Not Found): Can’t find a configuration for the country and state (or subdivision) specified in the request JSON.
- `500` (Internal Server Error): Encountered some other error. This response code doesn’t necessarily indicate a problem with the request.

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)