From e4574dfd7139b1b60ac4eefb1484f2e544a84634 Mon Sep 17 00:00:00 2001 From: Olufunke Moronfolu Date: Fri, 16 Oct 2026 14:10:29 +0200 Subject: [PATCH 1/3] PAT switch and API Keys deprecation for certain MxCloud APIs --- .../apidocs/deployment/backups-api-v2.md | 27 +++++++++++--- .../apidocs/deployment/build-api.md | 33 ++++++++++++++--- .../apidocs/deployment/deploy-api-1.md | 32 ++++++++++++++--- .../apidocs/deployment/deploy-api-2.md | 35 ++++++++++++++++--- .../apidocs/deployment/deploy-api-4.md | 8 +---- .../en/docs/releasenotes/deployment/_index.md | 2 +- .../deployment/mendix-cloud/_index.md | 10 ++++++ .../partials/landingpage/latest-releases.html | 2 +- .../api-key-deprecation-warning.md | 1 + .../apidocs-mxsdk/migrate-api-key-to-pat.md | 6 ++++ 10 files changed, 129 insertions(+), 27 deletions(-) create mode 100644 static/_includes/apidocs-mxsdk/api-key-deprecation-warning.md create mode 100644 static/_includes/apidocs-mxsdk/migrate-api-key-to-pat.md diff --git a/content/en/docs/apidocs-mxsdk/apidocs/deployment/backups-api-v2.md b/content/en/docs/apidocs-mxsdk/apidocs/deployment/backups-api-v2.md index 135078d2949..f9ffa0530ce 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/deployment/backups-api-v2.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/deployment/backups-api-v2.md @@ -21,21 +21,38 @@ You cannot currently upload an archive through this API. This function is curren This API focuses on working with snapshots and archives asynchronously, because these can be very long-running tasks for large quantities of data. It replaces the deprecated Backups API v1. -## Authentication +## Authentication{#authentication} -The Backups API requires authentication via API keys that are bound to your Mendix account. +The Backups API supports authentication via a personal access token (PAT) or an API key. Mendix recommends using a PAT. -### Obtaining an API Key +{{% alert color="warning" %}} +{{% snippet file="/static/_includes/apidocs-mxsdk/api-key-deprecation-warning.md" %}} +{{% /alert %}} -To obtain a Mendix API key, follow the instructions in the [API Keys](/portal/user-settings/#profile-api-keys) section of *Mendix Profile*. +### Authenticating with a PAT{#authenticating-with-pat} + +For details on how to generate a PAT, see the [Personal Access Tokens](/portal/user-settings/#pat) section of *Mendix Profile*. + +Each request must contain an `Authorization` header with the value `MxToken {GENERATED_PAT}`. Here is an example: + +```http +GET /api/v2/apps/543857rfds-dfsfsd12c5e24-3224d32eg/environments/cd5fc610-edb0-43c5-a374-0439a6411ace/snapshots HTTP/1.1 +Authorization: MxToken 7LJE…vk +``` + +### Authenticating with an API Key{#authenticating-with-api-key} -### Using Authentication Headers +To obtain a Mendix API key, follow the instructions in the [API Keys](/portal/user-settings/#profile-api-keys) section of *Mendix Profile*. Use the following request headers to authenticate an API call: * `Mendix-Username` – the login name of the requesting user with the required privileges in the Mendix Platform * `Mendix-ApiKey` – the API key of this user +### Migrating from an API Key to a PAT{#migrate-to-pat} + +{{% snippet file="/static/_includes/apidocs-mxsdk/migrate-api-key-to-pat.md" %}} + ### Configuring Permissions To perform an action via the Backups API, you need **Backups Access** and **API Access** permissions. This can be configured from the [Permissions tab](/developerportal/deploy/node-permissions/#permissions-tab) of your app's **Environments** page. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/deployment/build-api.md b/content/en/docs/apidocs-mxsdk/apidocs/deployment/build-api.md index f7a1a9a1f3a..d6469e7c1c9 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/deployment/build-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/deployment/build-api.md @@ -20,21 +20,44 @@ The image below provides a domain model representation of the concepts discussed {{< figure src="/attachments/apidocs-mxsdk/apidocs/build-api/api-model.png" class="no-border" >}} -## Authentication +## Authentication{#authentication} -The Build API requires authentication via API keys that are bound to your Mendix account. +The Build API supports authentication via a personal access token (PAT) or an API key. Mendix recommends using a PAT. -### Obtaining an API Key +{{% alert color="warning" %}} +{{% snippet file="/static/_includes/apidocs-mxsdk/api-key-deprecation-warning.md" %}} +{{% /alert %}} -To obtain a Mendix API key, follow the instructions in the [API Keys](/portal/user-settings/#profile-api-keys) section of *Mendix Profile*. +### Authenticating with a PAT{#authenticating-with-pat} + +For details on how to generate a PAT, see the [Personal Access Tokens](/portal/user-settings/#pat) section of *Mendix Profile*. + +Select at least the following scopes: + +* `mx:build:read` – to read build information +* `mx:build:write` – to trigger and manage builds + +Each request must contain an `Authorization` header with the value `MxToken {GENERATED_PAT}`. Here is an example: + +```http +GET /api/1/apps/calc/packages HTTP/1.1 +Host: deploy.mendix.com +Authorization: MxToken 7LJE…vk +``` -### Using Authentication Headers +### Authenticating with an API Key{#authenticating-with-api-key} + +To obtain a Mendix API key, follow the instructions in the [API Keys](/portal/user-settings/#profile-api-keys) section of *Mendix Profile*. Use the following request headers to authenticate an API call: * `Mendix-Username` – the login name of the requesting user with the required privileges in the Mendix Platform * `Mendix-ApiKey` – the API key of this user +### Migrating from an API Key to a PAT{#migrate-to-pat} + +{{% snippet file="/static/_includes/apidocs-mxsdk/migrate-api-key-to-pat.md" %}} + ### Configuring Permissions To perform an action via the Build API, you need **API Access** permissions. This can be configured from the [Permissions tab](/developerportal/deploy/node-permissions/#permissions-tab) of your app's **Environments** page. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-1.md b/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-1.md index 2f93c0b69d3..3a771640d58 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-1.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-1.md @@ -32,19 +32,43 @@ This image provides a domain model representation of the concepts discussed belo ## Authentication{#authentication} -The Deploy API v1 requires authentication via API keys that are bound to your Mendix account. +The Deploy API v1 supports authentication via a personal access token (PAT) or an API key. Mendix recommends using a PAT. -### Obtaining an API Key +{{% alert color="warning" %}} +{{% snippet file="/static/_includes/apidocs-mxsdk/api-key-deprecation-warning.md" %}} +{{% /alert %}} -To obtain a Mendix API key, follow the instructions in the [API Keys](/portal/user-settings/#profile-api-keys) section of *Mendix Profile*. +### Authenticating with a PAT{#authenticating-with-pat} + +For details on how to generate a PAT, see the [Personal Access Tokens](/portal/user-settings/#pat) section of *Mendix Profile*. -### Using Authentication Headers +Select at least the following scopes: + +* `mx:deployment:read` – to perform `GET` operations +* `mx:deployment:write` – to perform all operations (`GET`, `POST`, `PUT`, and `DELETE`) +* `mx:build:read` – to read build information +* `mx:build:write` – to trigger and manage builds + +Each request must contain an `Authorization` header with the value `MxToken {GENERATED_PAT}`. Here is an example: + +```http +GET /api/1/apps HTTP/1.1 +Authorization: MxToken 7LJE…vk +``` + +### Authenticating with an API Key{#authenticating-with-api-key} + +To obtain a Mendix API key, follow the instructions in the [API Keys](/portal/user-settings/#profile-api-keys) section of *Mendix Profile*. Use the following request headers to authenticate an API call: * `Mendix-Username` – the login name of the requesting user with the required privileges in the Mendix Platform * `Mendix-ApiKey` – the API key of this user +### Migrating from an API Key to a PAT{#migrate-to-pat} + +{{% snippet file="/static/_includes/apidocs-mxsdk/migrate-api-key-to-pat.md" %}} + ### Configuring Permissions Because APIs are designed for automated systems, the Deploy API does not require two-factor authentication, which is normally required to make changes to production environments. This is a potential security risk. Therefore, API access must be explicitly allowed for team members who want to use the Deploy API. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-2.md b/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-2.md index c7c749ec2bd..014481a89f3 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-2.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-2.md @@ -23,19 +23,46 @@ The v2 Deploy API only supports the endpoints listed here. For all other deploym Mendix recommends using calls from the same version of the API where possible. This is because the naming varies across versions. For example, the `{appId}` in the version 4 API is retrieved as the `{ProjectId}` from the version 1 API. {{% /alert %}} -The Deploy API v2 requires authentication via API keys that are bound to your Mendix account. +## Authentication{#authentication} -### Obtaining an API Key +The Deploy API v2 supports authentication via a personal access token (PAT) or an API key. Mendix recommends using a PAT. -To obtain a Mendix API key, follow the instructions in the [API Keys](/portal/user-settings/#profile-api-keys) section of *Mendix Profile*. +{{% alert color="warning" %}} +{{% snippet file="/static/_includes/apidocs-mxsdk/api-key-deprecation-warning.md" %}} +{{% /alert %}} + +### Authenticating with a PAT{#authenticating-with-pat} -### Using Authentication Headers +For details on how to generate a PAT, see the [Personal Access Tokens](/portal/user-settings/#pat) section of *Mendix Profile*. + +Select at least the following scopes: + +* `mx:deployment:read` – to perform `GET` operations +* `mx:deployment:write` – to perform all operations (`GET`, `POST`, `PUT`, and `DELETE`) +* `mx:build:read` – to read build information +* `mx:build:write` – to trigger and manage builds + +Each request must contain an `Authorization` header with the value `MxToken {GENERATED_PAT}`. Here is an example: + +```http +GET /api/v2/apps/calc/jobs/66046953-ecf7-4550-a889-4b7e9f1e1705 HTTP/1.1 +Host: deploy.mendix.com +Authorization: MxToken 7LJE…vk +``` + +### Authenticating with an API Key{#authenticating-with-api-key} + +To obtain a Mendix API key, follow the instructions in the [API Keys](/portal/user-settings/#profile-api-keys) section of *Mendix Profile*. Use the following request headers to authenticate an API call: * `Mendix-Username` – the login name of the requesting user with the required privileges in the Mendix Platform * `Mendix-ApiKey` – the API key of this user +### Migrating from an API Key to a PAT{#migrate-to-pat} + +{{% snippet file="/static/_includes/apidocs-mxsdk/migrate-api-key-to-pat.md" %}} + ### Configuring Permissions Because APIs are designed for automated systems, the Deploy API does not require two-factor authentication, which is normally required to make changes to production environments. This is a potential security risk. Therefore, API access must be explicitly allowed for team members who want to use the Deploy API. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-4.md b/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-4.md index f9768459635..ee6ef9069ff 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-4.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/deployment/deploy-api-4.md @@ -28,19 +28,13 @@ Mendix recommends using calls from the same version of the API where possible. T ## Authentication{#authentication} -Authentication for the Deploy API v4 uses a personal access token (PAT). - -### Generating a PAT - -For details on how to generate a PAT, see the [Personal Access Tokens](/portal/user-settings/#pat) section of *Mendix Profile*. +Authentication for the Deploy API v4 uses a personal access token (PAT). For details on how to generate a PAT, see the [Personal Access Tokens](/portal/user-settings/#pat) section of *Mendix Profile*. Select at least the following as **Deployment Mendix Cloud** scopes: * `mx:deployment:read` – to perform `GET` operations * `mx:deployment:write` – to perform all operations (`GET`, `POST`, `PUT`, and `DELETE`) -Store the generated value `{GENERATED_PAT}` somewhere safe so you can use it to authorize your Mendix Cloud Deploy API calls. - ### Using the PAT Each request must contain an `Authorization` header with the value `MxToken {GENERATED_PAT}`. Here is an example: diff --git a/content/en/docs/releasenotes/deployment/_index.md b/content/en/docs/releasenotes/deployment/_index.md index 812b17c4ecb..da997cb732d 100644 --- a/content/en/docs/releasenotes/deployment/_index.md +++ b/content/en/docs/releasenotes/deployment/_index.md @@ -15,7 +15,7 @@ Follow the links in the table below to see the release notes you want: | Type of Deployment | Last Updated | | --- | --- | -| [Mendix Cloud](/releasenotes/developer-portal/mendix-cloud/) | October 15, 2026 | +| [Mendix Cloud](/releasenotes/developer-portal/mendix-cloud/) | October 18, 2026 | | [Mendix on Kubernetes](/releasenotes/developer-portal/mendix-for-private-cloud/) | June 11, 2026 | | [Mendix on Azure](/releasenotes/developer-portal/mendix-on-azure/) | July 2, 2026 | | [SAP Business Technology Platform (SAP BTP)](/releasenotes/developer-portal/sap-cloud-platform/) | September 28, 2025 | diff --git a/content/en/docs/releasenotes/deployment/mendix-cloud/_index.md b/content/en/docs/releasenotes/deployment/mendix-cloud/_index.md index 2fa5aca7183..ca5dac6336f 100644 --- a/content/en/docs/releasenotes/deployment/mendix-cloud/_index.md +++ b/content/en/docs/releasenotes/deployment/mendix-cloud/_index.md @@ -16,6 +16,16 @@ For information on the current status of deployment to Mendix Cloud and any plan ## October 2026 +### October 18, 2026 + +#### New Features + +* The [Deploy API v1](/apidocs-mxsdk/apidocs/deploy-api/), [Deploy API v2](/apidocs-mxsdk/apidocs/deploy-api-2/), [Build API](/apidocs-mxsdk/apidocs/build-api/), and [Backups API v2](/apidocs-mxsdk/apidocs/backups-api/) now support authentication with personal access tokens (PATs) in addition to API keys. + +#### Deprecations + +* API keys are now deprecated, and support ends on January 1, 2027 for [Deploy API v1](/apidocs-mxsdk/apidocs/deploy-api/), [Deploy API v2](/apidocs-mxsdk/apidocs/deploy-api-2/), [Build API](/apidocs-mxsdk/apidocs/build-api/), and [Backups API v2](/apidocs-mxsdk/apidocs/backups-api/). To keep using these APIs, [migrate to PATs](/apidocs-mxsdk/apidocs/deploy-api/#migrate-to-pat). + ### October 15, 2026 #### New Features diff --git a/layouts/partials/landingpage/latest-releases.html b/layouts/partials/landingpage/latest-releases.html index f8124d46402..141e373360d 100644 --- a/layouts/partials/landingpage/latest-releases.html +++ b/layouts/partials/landingpage/latest-releases.html @@ -14,7 +14,7 @@

Latest Releases

  • Deployment -

    October 15, 2026

    +

    October 18, 2026

  • Catalog Release 2.150.0 diff --git a/static/_includes/apidocs-mxsdk/api-key-deprecation-warning.md b/static/_includes/apidocs-mxsdk/api-key-deprecation-warning.md new file mode 100644 index 00000000000..f3ab52979ab --- /dev/null +++ b/static/_includes/apidocs-mxsdk/api-key-deprecation-warning.md @@ -0,0 +1 @@ +API keys are deprecated, and support ends on January 1, 2027. To keep using this API, [migrate to personal access tokens (PATs)](#migrate-to-pat). diff --git a/static/_includes/apidocs-mxsdk/migrate-api-key-to-pat.md b/static/_includes/apidocs-mxsdk/migrate-api-key-to-pat.md new file mode 100644 index 00000000000..729cd8cc6de --- /dev/null +++ b/static/_includes/apidocs-mxsdk/migrate-api-key-to-pat.md @@ -0,0 +1,6 @@ +To switch an existing integration from an API key to a PAT, do the following: + +1. [Generate a PAT](#authenticating-with-pat) with the required scopes. +2. Remove the `Mendix-Username` and `Mendix-ApiKey` headers. +3. Add an `Authorization` header with the value `MxToken {GENERATED_PAT}`. +4. Run your integration to verify that the calls succeed. From 1f05d8d83e33f01d5833316728c3083ebb4e1fb6 Mon Sep 17 00:00:00 2001 From: Olufunke Moronfolu Date: Fri, 16 Oct 2026 14:23:02 +0200 Subject: [PATCH 2/3] Add PAT scope for Backups API authentication --- .../apidocs-mxsdk/apidocs/deployment/backups-api-v2.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/en/docs/apidocs-mxsdk/apidocs/deployment/backups-api-v2.md b/content/en/docs/apidocs-mxsdk/apidocs/deployment/backups-api-v2.md index f9ffa0530ce..fa478d6d9e6 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/deployment/backups-api-v2.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/deployment/backups-api-v2.md @@ -33,6 +33,11 @@ The Backups API supports authentication via a personal access token (PAT) or an For details on how to generate a PAT, see the [Personal Access Tokens](/portal/user-settings/#pat) section of *Mendix Profile*. +Select at least the following scopes: + +* `mx:deployment:read` – to perform `GET` operations +* `mx:deployment:write` – to perform all operations (`GET`, `POST`, `PUT`, and `DELETE`) + Each request must contain an `Authorization` header with the value `MxToken {GENERATED_PAT}`. Here is an example: ```http @@ -55,7 +60,7 @@ Use the following request headers to authenticate an API call: ### Configuring Permissions -To perform an action via the Backups API, you need **Backups Access** and **API Access** permissions. This can be configured from the [Permissions tab](/developerportal/deploy/node-permissions/#permissions-tab) of your app's **Environments** page. +To perform an action via the Backups API, you need **Backups Access** and **API Access** permissions. These permissions are required whether you authenticate with a PAT or an API key. PAT scopes alone are not enough. This can be configured from the [Permissions tab](/developerportal/deploy/node-permissions/#permissions-tab) of your app's **Environments** page. ## Examples From 4aebfefe1481a0e41f621f907dc72f8f6f70b101 Mon Sep 17 00:00:00 2001 From: Olufunke Moronfolu Date: Fri, 16 Oct 2026 14:44:15 +0200 Subject: [PATCH 3/3] Update release notes to include Cloud fixes --- .../en/docs/releasenotes/deployment/mendix-cloud/_index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/en/docs/releasenotes/deployment/mendix-cloud/_index.md b/content/en/docs/releasenotes/deployment/mendix-cloud/_index.md index ca5dac6336f..bbb880b9e5b 100644 --- a/content/en/docs/releasenotes/deployment/mendix-cloud/_index.md +++ b/content/en/docs/releasenotes/deployment/mendix-cloud/_index.md @@ -20,7 +20,12 @@ For information on the current status of deployment to Mendix Cloud and any plan #### New Features -* The [Deploy API v1](/apidocs-mxsdk/apidocs/deploy-api/), [Deploy API v2](/apidocs-mxsdk/apidocs/deploy-api-2/), [Build API](/apidocs-mxsdk/apidocs/build-api/), and [Backups API v2](/apidocs-mxsdk/apidocs/backups-api/) now support authentication with personal access tokens (PATs) in addition to API keys. +* The [Deploy API v1](/apidocs-mxsdk/apidocs/deploy-api/), [Deploy API v2](/apidocs-mxsdk/apidocs/deploy-api-2/), [Build API](/apidocs-mxsdk/apidocs/build-api/), and [Backups API v2](/apidocs-mxsdk/apidocs/backups-api/) now support authentication with personal access tokens (PATs), in addition to API keys. + +#### Fixes + +* We fixed an issue where failed deployments were incorrectly logged as successful. Failed deployments are now logged correctly, and a notification banner informs users when a deployment fails. (Tickets #287659, #289294) +* We fixed an issue with backups in sandbox apps that was caused by a missing environment display name. (Ticket #287851) #### Deprecations