PATCH | Partially update access policy by [id]

Description

Update selected settings of an access policy in PAM Core. Only the fields sent in the request body are changed, every other field keeps its current value, including fields in the same namespace. Namespaces themselves can be sent partially.

This is the endpoint to use for targeted changes. To update every setting in one request, access PUT | Update access policy by [id], which resets every field not sent.

To change only whether the policy is active, use POST | Activate access policy or POST | Deactivate access policy. The active field can't be modified through this endpoint.

Prerequisites

• An application with the Access Policy (V2) authorization granted by the administrator in A2A, and its PAM resource permission set to Read and write. For more information, access How to manage authorizations in A2A.
• A valid OAuth 2.0 access token. For more information, access How to authenticate an application in A2A.
• The current ETag value of the access policy, returned by GET | List an access policy by [id] and by every write operation on the policy.

Request

PATCH /api/v2/pam/access-policies/{id}

Path parameters

Headers

Request body

Send only the namespaces and fields you want to change. The body takes the same field names and types as POST | Create access policy access that article for the full field tables of the password, session, approvers_config, criteria, and access_limitation namespaces.

Fields that can't be modified

Sending any of these fields returns 422 with the code patch.field.not.allowed.

Example request

PATCH {{url}}/api/v2/pam/access-policies/3001

Headers

Content-Type: application/merge-patch+json
If-Match: "v2"

Body

{
    "password": {
        "require_approval": false,
        "approvals_required": 0
    }
}

This request changes two fields in the password namespace. Every other field in password and every other namespace, keeps its current value.

Response

HTTP/1.1 200 OK
ETag: "v3"

The ETag header holds the new version of the policy. Use this value in the If-Match header of the next write operation.

Example response body

The response returns the complete access policy, not only the fields that changed.

{
    "data": {
        "id": 3001,
        "access_policy": {
            "name": "PAM Administrators - Updated",
            "active": true,
            "description": "Updated description."
        },
        "password": {
            "allow_view": true,
            "view_mode": "complete",
            "require_reason": true,
            "require_approval": false,
            "approvals_required": 0,
            "disapprovals_to_cancel": 1,
            "approval_in_levels": true,
            "allow_emergency_access": false,
            "allow_change_expiration": true,
            "change_expiration_minutes": 60,
            "require_approval_days": false,
            "approval_days": [],
            "approval_times": [],
            "approval_custom_times": []
        },
        "session": {
            "allow_start": true,
            "block_during_freezing": true,
            "require_reason": true,
            "require_approval": true,
            "approvals_required": 2,
            "disapprovals_to_cancel": 1,
            "approval_in_levels": true,
            "allow_emergency_access": false,
            "require_change_id": true,
            "require_approval_days": false,
            "approval_days": [],
            "approval_times": [],
            "approval_custom_times": []
        },
        "approvers_config": {
            "governance_id_required": true,
            "always_add_user_manager": false
        },
        "criteria": {
            "site_ids": [1, 2],
            "device_type_ids": [3],
            "credential_type_ids": [5],
            "devices": [],
            "products": [],
            "usernames": [],
            "additional_information": [],
            "device_tags": ["prod", "staging"],
            "credential_tags": []
        },
        "access_limitation": {
            "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
            "times": ["08:00-18:00"],
            "custom_times": [],
            "period_start": null,
            "period_end": null
        }
    },
    "meta": {
        "links": { "self": "/api/v2/pam/access-policies/3001" },
        "actions": {
            "deactivate": "/api/v2/pam/access-policies/3001/deactivate"
        }
    }
}

Response body fields

The response returns the complete access policy, with the same fields as GET | List an access policy by [id]. Access that article for the full field tables.

Errors

Example error responses

412 the ETag doesn't match the policy's current version:

{
    "error": {
        "code": "api.precondition.failed",
        "message": "ETag does not match."
    }
}

422 the request body contains a field that can't be modified:

{
    "error": {
        "code": "patch.field.not.allowed",
        "message": "Field 'type' cannot be modified via PATCH."
    }
}

For authentication error messages and the 403 versus 404 policy, access API v2 - Conventions and shared behaviors.