From d1bc52fb1cc46deeb950f1feeb789b769ebf5df6 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 22:38:24 +0000 Subject: [PATCH 1/4] docs: document per-key IP allowlists for REST API keys --- api/introduction.mdx | 15 +++++++++++++++ es/api/introduction.mdx | 15 +++++++++++++++ zh/api/introduction.mdx | 15 +++++++++++++++ 3 files changed, 45 insertions(+) diff --git a/api/introduction.mdx b/api/introduction.mdx index e27b57833..617b1c1b6 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -96,3 +96,18 @@ Assistant API keys begin with the `mint_dsc_` prefix. Calls using the assistant API token can incur costs: either using your assistant credits or incurring overages. + +### Restrict keys by IP address + +You can optionally restrict an API key to a list of allowed IP addresses or CIDR ranges. When a key has an allowlist, requests from any other IP address are rejected with a `403` response. Both admin and assistant API keys support allowlists. + +Set the allowlist when you create the key on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. The allowlist is fixed for the lifetime of the key — to change it, delete the key and create a new one. If you don't set an allowlist, the key accepts requests from any IP address. + +Allowlist entries support: + +- IPv4 and IPv6 addresses, for example `203.0.113.5` or `2001:db8::1`. +- CIDR ranges, for example `198.51.100.0/24` or `2001:db8::/48`. + +Catch-all entries like `0.0.0.0/0` and `::/0` are not allowed. + +Use IP allowlists when your API key is called from a stable set of egress IPs — for example, a CI/CD runner, a static NAT gateway, or your backend server. Avoid allowlists for keys used from developer laptops or other environments with changing IPs. diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index f7339d44d..2a03ce679 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -81,3 +81,18 @@ Las keys del Assistant API comienzan con el prefijo `mint_dsc_`. Las llamadas que usan el token del Assistant API pueden generar costos: ya sea usando tus créditos del assistant o incurriendo en excedentes. + +### Restringir claves por dirección IP + +Puedes restringir opcionalmente una API key a una lista de direcciones IP o rangos CIDR permitidos. Cuando una key tiene una lista de permitidos, las solicitudes desde cualquier otra dirección IP se rechazan con una respuesta `403`. Tanto las claves de la API de administrador como las del Assistant API admiten listas de permitidos. + +Configura la lista de permitidos al crear la key en la [página de API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard. La lista de permitidos es fija durante la vida de la key; para cambiarla, elimina la key y crea una nueva. Si no configuras una lista de permitidos, la key acepta solicitudes desde cualquier dirección IP. + +Las entradas admiten: + +* Direcciones IPv4 e IPv6, por ejemplo `203.0.113.5` o `2001:db8::1`. +* Rangos CIDR, por ejemplo `198.51.100.0/24` o `2001:db8::/48`. + +No se permiten entradas comodín como `0.0.0.0/0` o `::/0`. + +Usa listas de IP permitidas cuando tu API key se llame desde un conjunto estable de IPs de salida, por ejemplo, un runner de CI/CD, una NAT estática o el servidor de tu backend. Evita las listas de permitidos para keys usadas desde portátiles de personas desarrolladoras u otros entornos con IPs cambiantes. diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index cc1bd34b3..79030441d 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -81,3 +81,18 @@ assistant API key 以 `mint_dsc_` 前缀开头。 使用 assistant API token 进行的调用可能会产生费用：可能会消耗你的助手额度，或产生超额费用。 + +### 按 IP 地址限制 key + +你可以选择将 API key 限制为一组允许的 IP 地址或 CIDR 范围。当 key 设置了允许列表时，来自任何其他 IP 地址的请求都会以 `403` 响应被拒绝。管理员 API key 和 assistant API key 都支持允许列表。 + +在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 创建 key 时设置允许列表。允许列表在 key 的生命周期内固定不变——要更改它，请删除该 key 并创建一个新的。如果不设置允许列表，key 会接受来自任何 IP 地址的请求。 + +允许列表条目支持： + +* IPv4 和 IPv6 地址，例如 `203.0.113.5` 或 `2001:db8::1`。 +* CIDR 范围，例如 `198.51.100.0/24` 或 `2001:db8::/48`。 + +不允许使用 `0.0.0.0/0` 和 `::/0` 等通配条目。 + +当你的 API key 从一组固定的出口 IP 调用时，请使用 IP 允许列表——例如 CI/CD 运行器、静态 NAT 网关或你的后端服务器。对于从开发者笔记本电脑或其他 IP 会变化的环境使用的 key，请避免使用允许列表。 From 9a92d848ff16d6c785733ca973a47b4868031196 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 22:40:10 +0000 Subject: [PATCH 2/4] docs: add French translation and heading anchors for IP allowlist section --- es/api/introduction.mdx | 4 +++- fr/api/introduction.mdx | 17 +++++++++++++++++ zh/api/introduction.mdx | 4 +++- 3 files changed, 23 insertions(+), 2 deletions(-) diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 2a03ce679..8ed9d40a1 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -82,7 +82,9 @@ Las keys del Assistant API comienzan con el prefijo `mint_dsc_`. Las llamadas que usan el token del Assistant API pueden generar costos: ya sea usando tus créditos del assistant o incurriendo en excedentes. -### Restringir claves por dirección IP +
+ ### Restringir claves por dirección IP +
Puedes restringir opcionalmente una API key a una lista de direcciones IP o rangos CIDR permitidos. Cuando una key tiene una lista de permitidos, las solicitudes desde cualquier otra dirección IP se rechazan con una respuesta `403`. Tanto las claves de la API de administrador como las del Assistant API admiten listas de permitidos. diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index dce160103..73d4b0cd6 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -81,3 +81,20 @@ Les clés d'API de l'Assistant commencent par le préfixe `mint_dsc_`. Les appels utilisant le token de l'API de l'Assistant peuvent entraîner des coûts : soit en utilisant vos crédits d'Assistant, soit en engendrant des dépassements. + +
+ ### Restreindre les clés par adresse IP +
+ +Vous pouvez éventuellement restreindre une clé d'API à une liste d'adresses IP ou de plages CIDR autorisées. Lorsqu'une clé possède une liste d'autorisation, les requêtes provenant de toute autre adresse IP sont rejetées avec une réponse `403`. Les clés d'API administrateur et les clés d'API de l'Assistant prennent en charge les listes d'autorisation. + +Configurez la liste d'autorisation lors de la création de la clé sur la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard. La liste d'autorisation est fixée pour toute la durée de vie de la clé — pour la modifier, supprimez la clé et créez-en une nouvelle. Si vous ne définissez pas de liste d'autorisation, la clé accepte les requêtes depuis n'importe quelle adresse IP. + +Les entrées de la liste prennent en charge : + +* Les adresses IPv4 et IPv6, par exemple `203.0.113.5` ou `2001:db8::1`. +* Les plages CIDR, par exemple `198.51.100.0/24` ou `2001:db8::/48`. + +Les entrées attrape-tout comme `0.0.0.0/0` et `::/0` ne sont pas autorisées. + +Utilisez les listes d'IP autorisées lorsque votre clé d'API est appelée depuis un ensemble stable d'IP de sortie — par exemple un runner CI/CD, une passerelle NAT statique ou votre serveur backend. Évitez les listes d'autorisation pour les clés utilisées depuis des ordinateurs portables de développeurs ou d'autres environnements dont les IP changent. diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index 79030441d..dc799a82f 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -82,7 +82,9 @@ assistant API key 以 `mint_dsc_` 前缀开头。 使用 assistant API token 进行的调用可能会产生费用：可能会消耗你的助手额度，或产生超额费用。 -### 按 IP 地址限制 key +
+ ### 按 IP 地址限制 key +
你可以选择将 API key 限制为一组允许的 IP 地址或 CIDR 范围。当 key 设置了允许列表时，来自任何其他 IP 地址的请求都会以 `403` 响应被拒绝。管理员 API key 和 assistant API key 都支持允许列表。 From ac06ac1ed3d8e53337b2b61b16592ff6aad5debb Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 23:32:20 +0000 Subject: [PATCH 3/4] docs: document read/write scopes for admin API keys --- api/introduction.mdx | 17 +++++++++++++++++ es/api/introduction.mdx | 19 +++++++++++++++++++ fr/api/introduction.mdx | 19 +++++++++++++++++++ zh/api/introduction.mdx | 19 +++++++++++++++++++ 4 files changed, 74 insertions(+) diff --git a/api/introduction.mdx b/api/introduction.mdx index 617b1c1b6..94deacc4d 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -111,3 +111,20 @@ Allowlist entries support: Catch-all entries like `0.0.0.0/0` and `::/0` are not allowed. Use IP allowlists when your API key is called from a stable set of egress IPs — for example, a CI/CD runner, a static NAT gateway, or your backend server. Avoid allowlists for keys used from developer laptops or other environments with changing IPs. + +### Restrict admin keys by scope + +You can optionally restrict an admin API key to `read` or `write` scopes. Scopes apply only to admin API keys; assistant API keys are unaffected. + +Set scopes when you create the key on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Scopes are fixed for the lifetime of the key — to change them, delete the key and create a new one. If you don't set any scopes, the key can call every admin endpoint (existing keys keep working). + +Mintlify derives the required scope from the HTTP method of the request: + +| HTTP method | Required scope | +| -------------- | -------------- | +| `GET`, `HEAD` | `read` | +| All others | `write` | + +A key with `write` also satisfies `read`, so `["read", "write"]` and `["write"]` both allow every endpoint. Requests that require a scope the key does not have are rejected with a `403` response. + +Only `read` and `write` are accepted. Any other value returns a `400` response at key creation. diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 8ed9d40a1..6137e2344 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -98,3 +98,22 @@ Las entradas admiten: No se permiten entradas comodín como `0.0.0.0/0` o `::/0`. Usa listas de IP permitidas cuando tu API key se llame desde un conjunto estable de IPs de salida, por ejemplo, un runner de CI/CD, una NAT estática o el servidor de tu backend. Evita las listas de permitidos para keys usadas desde portátiles de personas desarrolladoras u otros entornos con IPs cambiantes. + +
+ ### Restringir claves de administrador por scope +
+ +Puedes restringir opcionalmente una clave de la API de administrador a los scopes `read` o `write`. Los scopes se aplican solo a las claves de la API de administrador; las keys del Assistant API no se ven afectadas. + +Configura los scopes al crear la key en la [página de API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard. Los scopes son fijos durante la vida de la key; para cambiarlos, elimina la key y crea una nueva. Si no configuras scopes, la key puede llamar a todos los endpoints de administrador (las keys existentes siguen funcionando). + +Mintlify deriva el scope requerido a partir del método HTTP de la solicitud: + +| Método HTTP | Scope requerido | +| -------------- | --------------- | +| `GET`, `HEAD` | `read` | +| Los demás | `write` | + +Una key con `write` también satisface `read`, por lo que `["read", "write"]` y `["write"]` permiten todos los endpoints. Las solicitudes que requieren un scope que la key no tiene se rechazan con una respuesta `403`. + +Solo se aceptan `read` y `write`. Cualquier otro valor devuelve una respuesta `400` al crear la key. diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index 73d4b0cd6..72ced42b8 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -98,3 +98,22 @@ Les entrées de la liste prennent en charge : Les entrées attrape-tout comme `0.0.0.0/0` et `::/0` ne sont pas autorisées. Utilisez les listes d'IP autorisées lorsque votre clé d'API est appelée depuis un ensemble stable d'IP de sortie — par exemple un runner CI/CD, une passerelle NAT statique ou votre serveur backend. Évitez les listes d'autorisation pour les clés utilisées depuis des ordinateurs portables de développeurs ou d'autres environnements dont les IP changent. + +
+ ### Restreindre les clés administrateur par scope +
+ +Vous pouvez éventuellement restreindre une clé d'API administrateur aux scopes `read` ou `write`. Les scopes s'appliquent uniquement aux clés d'API administrateur ; les clés d'API de l'Assistant ne sont pas concernées. + +Définissez les scopes lors de la création de la clé sur la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard. Les scopes sont fixés pour toute la durée de vie de la clé — pour les modifier, supprimez la clé et créez-en une nouvelle. Si vous ne définissez aucun scope, la clé peut appeler tous les points de terminaison administrateur (les clés existantes continuent de fonctionner). + +Mintlify déduit le scope requis à partir de la méthode HTTP de la requête : + +| Méthode HTTP | Scope requis | +| -------------- | ------------ | +| `GET`, `HEAD` | `read` | +| Les autres | `write` | + +Une clé disposant de `write` satisfait également `read`, donc `["read", "write"]` et `["write"]` autorisent tous les points de terminaison. Les requêtes qui nécessitent un scope que la clé ne possède pas sont rejetées avec une réponse `403`. + +Seuls `read` et `write` sont acceptés. Toute autre valeur renvoie une réponse `400` à la création de la clé. diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index dc799a82f..5ac704143 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -98,3 +98,22 @@ assistant API key 以 `mint_dsc_` 前缀开头。 不允许使用 `0.0.0.0/0` 和 `::/0` 等通配条目。 当你的 API key 从一组固定的出口 IP 调用时，请使用 IP 允许列表——例如 CI/CD 运行器、静态 NAT 网关或你的后端服务器。对于从开发者笔记本电脑或其他 IP 会变化的环境使用的 key，请避免使用允许列表。 + +
+ ### 按 scope 限制管理员 key +
+ +你可以选择将管理员 API key 限制为 `read` 或 `write` scope。scope 仅适用于管理员 API key；assistant API key 不受影响。 + +在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 创建 key 时设置 scope。scope 在 key 的生命周期内固定不变——要更改它们，请删除该 key 并创建一个新的。如果不设置任何 scope，该 key 可以调用所有管理员端点（现有 key 保持不变）。 + +Mintlify 根据请求的 HTTP 方法推导所需的 scope： + +| HTTP 方法 | 所需 scope | +| -------------- | ---------- | +| `GET`、`HEAD` | `read` | +| 其他所有方法 | `write` | + +拥有 `write` 的 key 也满足 `read`，因此 `["read", "write"]` 和 `["write"]` 都允许调用所有端点。需要某个 key 未拥有的 scope 的请求会以 `403` 响应被拒绝。 + +仅接受 `read` 和 `write`。创建 key 时使用任何其他值都会返回 `400` 响应。 From 45cfefcdcddfe14a4821822e2001339933429790 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 8 Jul 2026 00:07:14 +0000 Subject: [PATCH 4/4] docs: document optional expiration date for API keys --- api/introduction.mdx | 10 ++++++++++ es/api/introduction.mdx | 12 ++++++++++++ fr/api/introduction.mdx | 12 ++++++++++++ zh/api/introduction.mdx | 12 ++++++++++++ 4 files changed, 46 insertions(+) diff --git a/api/introduction.mdx b/api/introduction.mdx index 94deacc4d..616803c2d 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -128,3 +128,13 @@ Mintlify derives the required scope from the HTTP method of the request: A key with `write` also satisfies `read`, so `["read", "write"]` and `["write"]` both allow every endpoint. Requests that require a scope the key does not have are rejected with a `403` response. Only `read` and `write` are accepted. Any other value returns a `400` response at key creation. + +### Set an expiration date + +You can optionally set an expiration date on any API key at creation. After the expiration timestamp passes, requests using the key are rejected. Both admin and assistant API keys support expiration. + +Set the expiration on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. The expiration is fixed for the lifetime of the key — to change it, delete the key and create a new one. If you don't set an expiration, the key never expires. + +The expiration must be a future ISO 8601 timestamp. Past or invalid timestamps return a `400` response at key creation. The expiration is returned as `expiresAt` when you list keys, or `null` for keys with no expiration. + +Use expirations for short-lived credentials such as CI/CD tokens, external contractors, or one-off scripts. Rotate long-lived keys by creating a replacement, updating your integrations, and deleting the old key. diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 6137e2344..a31a324af 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -117,3 +117,15 @@ Mintlify deriva el scope requerido a partir del método HTTP de la solicitud: Una key con `write` también satisface `read`, por lo que `["read", "write"]` y `["write"]` permiten todos los endpoints. Las solicitudes que requieren un scope que la key no tiene se rechazan con una respuesta `403`. Solo se aceptan `read` y `write`. Cualquier otro valor devuelve una respuesta `400` al crear la key. + +
+ ### Establecer una fecha de expiración +
+ +Puedes establecer opcionalmente una fecha de expiración en cualquier API key al crearla. Cuando pasa la marca de tiempo de expiración, las solicitudes que usan la key se rechazan. Tanto las claves de la API de administrador como las del Assistant API admiten expiración. + +Configura la expiración en la [página de API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard. La expiración es fija durante la vida de la key; para cambiarla, elimina la key y crea una nueva. Si no configuras una expiración, la key nunca expira. + +La expiración debe ser una marca de tiempo ISO 8601 en el futuro. Las marcas de tiempo pasadas o inválidas devuelven una respuesta `400` al crear la key. La expiración se devuelve como `expiresAt` al listar las keys, o `null` para las keys sin expiración. + +Usa expiraciones para credenciales de corta duración, como tokens de CI/CD, colaboradores externos o scripts puntuales. Rota las keys de larga duración creando una de reemplazo, actualizando tus integraciones y eliminando la anterior. diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index 72ced42b8..d482d45e9 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -117,3 +117,15 @@ Mintlify déduit le scope requis à partir de la méthode HTTP de la requête : Une clé disposant de `write` satisfait également `read`, donc `["read", "write"]` et `["write"]` autorisent tous les points de terminaison. Les requêtes qui nécessitent un scope que la clé ne possède pas sont rejetées avec une réponse `403`. Seuls `read` et `write` sont acceptés. Toute autre valeur renvoie une réponse `400` à la création de la clé. + +
+ ### Définir une date d'expiration +
+ +Vous pouvez éventuellement définir une date d'expiration sur toute clé d'API lors de sa création. Une fois l'horodatage d'expiration dépassé, les requêtes utilisant la clé sont rejetées. Les clés d'API administrateur et les clés d'API de l'Assistant prennent en charge l'expiration. + +Définissez l'expiration sur la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard. L'expiration est fixée pour toute la durée de vie de la clé — pour la modifier, supprimez la clé et créez-en une nouvelle. Si vous ne définissez pas d'expiration, la clé n'expire jamais. + +L'expiration doit être un horodatage ISO 8601 futur. Les horodatages passés ou invalides renvoient une réponse `400` à la création de la clé. L'expiration est renvoyée sous la forme `expiresAt` lors de la liste des clés, ou `null` pour les clés sans expiration. + +Utilisez les expirations pour des identifiants à courte durée de vie tels que des tokens CI/CD, des prestataires externes ou des scripts ponctuels. Faites tourner les clés de longue durée en créant une clé de remplacement, en mettant à jour vos intégrations, puis en supprimant l'ancienne. diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index 5ac704143..26681d950 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -117,3 +117,15 @@ Mintlify 根据请求的 HTTP 方法推导所需的 scope： 拥有 `write` 的 key 也满足 `read`，因此 `["read", "write"]` 和 `["write"]` 都允许调用所有端点。需要某个 key 未拥有的 scope 的请求会以 `403` 响应被拒绝。 仅接受 `read` 和 `write`。创建 key 时使用任何其他值都会返回 `400` 响应。 + +
+ ### 设置过期日期 +
+ +你可以在创建任何 API key 时选择性地设置过期日期。过期时间戳过后，使用该 key 的请求将被拒绝。管理员 API key 和 assistant API key 都支持过期设置。 + +在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 设置过期时间。过期时间在 key 的生命周期内固定不变——要更改它，请删除该 key 并创建一个新的。如果不设置过期时间，该 key 永不过期。 + +过期时间必须是未来的 ISO 8601 时间戳。过去或无效的时间戳在创建 key 时会返回 `400` 响应。列出 key 时会以 `expiresAt` 返回过期时间；没有过期时间的 key 返回 `null`。 + +将过期时间用于短期凭据，例如 CI/CD 令牌、外部合作者或一次性脚本。对于长期使用的 key，可通过创建替代 key、更新集成、然后删除旧 key 的方式进行轮换。