Actualizar una API

PATCH /v1/apis/{api_id} · permiso apis:write

Actualiza una API con un parche de fusión JSON (RFC 7396, application/merge-patch+json): los campos que envías cambian, los campos que omites se quedan. If-Match es requerido. key e identifier no pueden cambiar después de la creación, y la API del sistema no puede ser modificada. Un parche que no cambia nada no escribe nada y mantiene la versión.

Solicitud

Parámetro	En	Descripción
`api_id`	path	El id de la API.
`If-Match`	header	El `ETag` de la última lectura (requerido).

Cuerpo: cualquiera de los campos escribibles abajo (todos opcionales). Un campo no puede ser removido con null.

Campo	Tipo	Requerido	Descripción
`key`	string	no	Clave de configuración estable, `^[a-z0-9_-]{1,64}$`. Inmutable.
`identifier`	string	no	Audiencia de token: una URL https (sin consulta ni fragmento) o `urn:<nid>:<nss>`; almacenada en forma canónica. Inmutable. El espacio de nombres `urn:idp:` está reservado.
`name`	string	no	1-128 caracteres.
`access_token_lifetime_s`	integer	no	60-86400. Por defecto 3600 (600 con `mcp_profile`).
`token_format`	string	no	`jwt` (por defecto) u `opaque`.
`rbac_mode`	string	no	Cómo llegan los roles y permisos al token: `claims` (por defecto) añade `permissions` y `org_permissions`; `off` no añade ninguno (`org_roles` se sigue añadiendo); `enforce` los añade y además limita los scopes concedidos a los permisos efectivos del usuario.
`allow_offline_access`	boolean	no	Por defecto `true`.
`require_resource_indicator`	boolean	no	Por defecto `false` (`true` con `mcp_profile`).
`dpop_required`	boolean	no	Por defecto `false`.
`mcp_profile`	boolean	no	Requiere un `identifier` https y `require_resource_indicator: true`.
`first_party_access`	string	no	`all` (por defecto) u `granted_only`.
`introspection_applications`	array	no	Aplicaciones (`app_…`) que pueden introspeccionar los tokens de esta API, máximo 50, sin duplicados. Solo aplicaciones `web` y `m2m` del mismo entorno. La lista se reemplaza en su totalidad; `[]` la vacía, `null` se rechaza.

Aplicaciones de introspeción

El punto de conexión de introspeción (POST <issuer>/oauth2/introspect, RFC 7662) responde con active: true para un token de acceso solo a dos llamadores: la aplicación a la que se emitió el token, o una aplicación en la lista introspection_applications de la API nombrada en el aud del token. Todos los demás llamadores reciben active: false, por lo que las API no pueden leer los tokens entre sí. Solo las aplicaciones confidenciales (web, m2m) del mismo entorno pueden listarse; la lista se almacena como un conjunto y se devuelve en orden de ID. Una aplicación suspendida permanece en la lista pero no puede introspeccionar. La lista de la API del sistema no se puede escribir.

Respuesta

200 OK con el nuevo ETag:

{
  "id": "api_01h455vb4pex5vsknk084sn02q",
  "key": "orders",
  "identifier": "https://api.example.com/orders",
  "name": "Orders API",
  "is_system": false,
  "access_token_lifetime_s": 3600,
  "token_format": "jwt",
  "rbac_mode": "off",
  "allow_offline_access": true,
  "require_resource_indicator": false,
  "dpop_required": false,
  "mcp_profile": false,
  "first_party_access": "all",
  "introspection_applications": ["app_01h455vb4pex5vsknk084sn02r"],
  "created_at": "2026-10-05T12:00:00Z",
  "updated_at": "2026-10-05T12:00:00Z"
}

Errores

HTTP	código	Cuándo
400	`unknown_field`	El parche contiene un campo de solo lectura o desconocido.
404	`not_found`	No existe tal API en este entorno.
409	`conflict`	La API es la API del sistema.
412	`precondition_failed`	`If-Match` no coincide con la versión actual.
415	`unsupported_media_type`	El tipo de contenido no es `application/merge-patch+json`.
422	`validation_failed`	Un valor es inválido, un campo fue configurado a `null`, o `key` / `identifier` fue cambiado.
422	`validation_failed`	Un elemento `introspection_applications` no existe en este entorno (`unknown_application`), no es confidencial (`not_confidential`), es un duplicado (`duplicate`) o no es un ID `app_…` (`invalid_value`); el puntero nombra el índice en la solicitud.
428	`precondition_required`	`If-Match` está faltando.

Ejemplo

curl -X PATCH https://api.eu.keenauth.com/v1/apis/api_01h455vb4pex5vsknk084sn02q \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"access_token_lifetime_s":900}'