Update Global Policy

Endpoint

PUT /apiops/projects/{projectName}/globalPolicies/{policyName}/

Authentication

Requires a Personal API Access Token.

Header

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
policyName	string	Yes	Global policy name (the policy must already exist)

Query Parameters

None

Request Body

The body is the same polymorphic policy snapshot shape as Create Global Policy, with one hard requirement: the "_class" in the body must match the existing policy's concrete type — you cannot change a global policy's type via update. If "name" is omitted from the body it falls back to the policyName path variable; if present it must match (case-insensitive).

Full JSON Body Example - WS-Security Username Token

{
  "_class": "policy-ws-security-username",
  "name": "backend-ws-security",
  "description": "Username token injected before the request reaches the backend (rotated)",
  "active": true,
  "username": "backend-service",
  "password": "new-plaintext-password",
  "passwordType": "PasswordText",
  "mustUnderstand": true,
  "nonce": true,
  "created": true
}

Common Fields (all policy types)

Field	Type	Required	Default	Description
_class	string	Yes	-	Policy type discriminator — must equal the existing policy's type
name	string	No	path variable	Global policy name — if present must match the policyName path variable
description	string	No	-	Policy description
active	boolean	No	false	Whether the policy is active
oneWay	boolean	No	false	Fire-and-forget execution flag
trace	boolean	No	false	Policy-level trace logging flag
buildCustomMessage	boolean	No	false	Whether a custom error message template is used
customMessageTemplate	string	No	-	Custom error message template (used when buildCustomMessage=true)
customMessageContentType	string	No	application/json; charset=UTF-8	Content type of the custom error message
customMessageHttpStatusCode	integer	No	-	HTTP status code of the custom error message
policyCondition	object	No	-	Optional conditional-execution rule (same shape as the classic policy editors)

id, projectId and global are always preserved from the existing record — they are ignored if present in the body. Fields beyond the common set are specific to the chosen _class; see Create Global Policy for the full _class catalog.

Secret Contract (POST vs PUT)

Unlike Create Global Policy (which accepts pre-encrypted, cross-instance snapshots), PUT is the normal human-authored update path:

• @SecretData fields (e.g. password on WS-Security Username Token, clientSecret on OIDC) must be sent plaintext in the body. They are encrypted before the record is persisted.
• There is no blank-preserves-stored-value behavior on this endpoint. Sending an empty string for a secret field overwrites the stored value with an empty value — it does not keep the previously configured secret. Because Get Global Policy and List Global Policies never return the full policy body, you must resupply the correct secret value on every update that touches a secret-bearing policy type.

Notes

• The policy identified by policyName must already exist, otherwise a 400 is returned.
• The _class in the body must equal the existing policy's Java class, otherwise a 400 is returned — you cannot retype a policy through update.
• If name is present in the body it must match the policyName path variable (case-insensitive).

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "resultList": [
    {
      "id": "665f2a1c9b3e4a0012ab34ce",
      "name": "backend-ws-security",
      "policyType": "policy-ws-security-username",
      "policyTypeLabel": "policy-ws-security-username"
    }
  ],
  "resultCount": 1
}

Response Fields

Field	Type	Description
status	string	Response status: SUCCESS or FAILURE
resultList	array	Single-element list containing the updated policy's descriptor
resultCount	integer	Always 1 on success

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "Global policy (name: backend-ws-security) was not found!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "Policy type in body does not match the existing policy's type."
}

or

{
  "status": "FAILURE",
  "resultMessage": "Global policy name in path (backend-ws-security) does not match name in body (backend-ws-security-2)!"
}

Error Response (401 Unauthorized)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

cURL Example

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/globalPolicies/backend-ws-security/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "_class": "policy-ws-security-username",
    "name": "backend-ws-security",
    "description": "Username token injected before the request reaches the backend (rotated)",
    "active": true,
    "username": "backend-service",
    "password": "new-plaintext-password",
    "passwordType": "PasswordText",
    "mustUnderstand": true
  }'

Notes and Warnings

• Update-Only: Unlike Create Global Policy, PUT fails with a 400 when the named policy does not exist.
• Plaintext Secret Contract: @SecretData fields must be sent plaintext and are encrypted before persist — the opposite of what POST expects. See Secret Contract above.
• Cascades to Every Embedder: The updated policy is pushed into every API proxy, API proxy group and policy group that embeds it by id, so their embedded snapshots stay in sync with this change.
• Type Cannot Change: The _class in the body must match the existing policy's concrete type.
• Permission: Requires API_MANAGEMENT + MANAGE in the project.

Related Documentation

• Create Global Policy - Create a new global policy (pre-encrypted snapshot contract)
• Get Global Policy - Read a policy's descriptor back
• Delete Global Policy - Delete a global policy
• Global Policies API - Resource overview
• Authentication Guide - How to obtain and use API tokens
• Error Handling - Error response formats