PUT | Update access policy by [id]

Description

Update every setting of an access policy in PAM Core. The request body takes the same structure as POST | Create access policy.

Attention

Every setting not sent in the request body is reset, including settings in namespaces you omit entirely. To change a few fields and leave the rest untouched, use PATCH | Partially update access policy by [id] instead.

To change only whether the policy is active, use POST | Activate access policy or POST | Deactivate access policy. The active state isn't affected by 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.
The sites, device types, and credential types referenced in criteria must already exist.

Info

An access token carries only the authorizations that existed when it was generated. After the administrator enables Access Policy (V2), generate a new token for the application, an existing token won't gain the new authorization.

Request

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

Path parameters

Field	Type	Required	Description
`id`	integer	Yes	Unique identification code of the access policy. Note: this value is assigned by Segura® in POST \| Create access policy.

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`.
`If-Match`	Yes	The `ETag` value of the policy version being updated. The request is rejected with `412` when the value doesn't match the policy's current version.

Request body

The request body takes the same structure as POST | Create access policy. Access that article for the full field tables of the password, session, approvers_config, criteria, and access_limitation namespaces.

Field	Type	Required	Description
`name`	string	Yes	Name of the access policy. Leading and trailing spaces are trimmed and the result can't be empty.
`description`	string	No	Description of the access policy. Reset to `null` when not sent.
`password`	object	—	Rules for password access. Reset when not sent.
`session`	object	—	Rules for session access. Reset when not sent.
`approvers_config`	object	—	Approver behavior. Reset when not sent.
`criteria`	object	—	Rules that determine which resources the policy covers. Reset when not sent.
`access_limitation`	object	—	Time restrictions applied to the policy. Reset when not sent.

Example request

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

Headers

Content-Type: application/json
If-Match: "v1"

Body

{
    "name": "PAM Administrators - Updated",
    "description": "Updated description.",
    "password": {
        "allow_view": true,
        "view_mode": "complete",
        "require_reason": true,
        "require_approval": true,
        "approvals_required": 2,
        "disapprovals_to_cancel": 1,
        "approval_in_levels": true,
        "allow_emergency_access": false,
        "allow_change_expiration": true,
        "change_expiration_minutes": 60,
        "require_approval_days": false
    },
    "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
    },
    "approvers_config": {
        "governance_id_required": true,
        "always_add_user_manager": false
    },
    "criteria": {
        "site_ids": [1, 2],
        "device_type_ids": [3],
        "credential_type_ids": [5],
        "device_tags": ["prod", "staging"]
    },
    "access_limitation": {
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "times": ["08:00-18:00"],
        "period_start": null,
        "period_end": null
    }
}

Response

HTTP/1.1 200 OK
ETag: "v2"

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

{
    "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": true,
            "approvals_required": 2,
            "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"
        }
    }
}

In this example, credential_tags was omitted from the request and returns as an empty array, the reset behavior described above.

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.

Field	Type	Description
`data`	object	The updated access policy.
`data.id`	integer	Unique identification code of the access policy.
`data.access_policy`	object	Core attributes of the access policy.
`data.password`	object	Password access rules after the update.
`data.session`	object	Session access rules after the update.
`data.approvers_config`	object	Approver behavior after the update.
`data.criteria`	object	Rules covered by the policy after the update.
`data.access_limitation`	object	Time restrictions applied to the policy after the update.
`meta`	object	Resource metadata.
`meta.links.self`	string	Path of the access policy.
`meta.actions`	object	Actions available for the policy in its current state.

Errors

HTTP code	Message	Possible cause	Solution
`400`	`api.request.malformed`	The request body isn't valid JSON.	Check the body syntax and resend the request.
`401`	`api.auth.token.invalid`	The access token is missing or has expired.	Request a new access token.
`403`	`api.permission.denied`	The authorization doesn't have permission to update access policies.	Ask the administrator to check the Access Policy (V2) authorization and the PAM resource permission in A2A, then generate a new token.
`404`	`api.resource.not_found`	The access policy doesn't exist, or it's outside the scope of the authorization.	Check the identification code sent in the path.
`409`	`api.resource.inactive`	The request tried to write to an inactive access policy.	Activate the policy with POST \| Activate access policy before updating it.
`412`	`api.precondition.failed`	The `If-Match` value doesn't match the policy's current version, which means the policy changed after it was read.	Retrieve the policy again with GET \| List an access policy by [id], review the changes, and resend the request with the new `ETag`.
`422`	`api.validation.required_field`	A required field is missing from the request body.	Add the missing field and resend the request.
`422`	`api.validation.invalid_reference`	A referenced site, device type, or credential type doesn't exist.	Check the identification codes sent in `criteria`.
`422`	`api.enum.invalid_value`	A field received a value outside its allowed list.	Check the allowed values for the field and resend the request.
`429`	`rate_limit_exceeded`	The request rate limit was exceeded.	Reduce the request rate and try again.
`500`	`api.internal.error`	Internal server error.	Contact the Segura® support team.

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