GET | List an access policy by [id]

Description

Retrieve the complete configuration of a single access policy in PAM Core. The response returns every namespace of the policy: its core attributes, password and session rules, approver behavior, criteria, and access time limitations.

To list the access policies available to your authorization, access GET | List all access policies, which returns a reduced set of fields for each policy.

Prerequisites

An application with the Access Policy (V2) authorization granted by the administrator in A2A, and its PAM resource permission set to Read-only or 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 identification code of the access policy, returned by POST | Create access policy or by GET | List all access policies.

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

GET /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.

Query parameters

Field	Type	Description
`fields`	string	Restricts the response to the listed fields. Supports every field available in the list and detail representations.

For the full field projection syntax, access API v2 - Conventions and shared behaviors.

Example request

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

Response

HTTP/1.1 200 OK
ETag: "v1"

The ETag header holds the current version of the policy. Keep this value PUT | Update access policy by [id], PATCH | Partially update access policy by [id], and DELETE | Delete access policy by [id] use it in the If-Match header to detect concurrent changes.

Example response body

{
    "data": {
        "id": 3001,
        "access_policy": {
            "name": "PAM Administrators",
            "active": true,
            "description": "Full access for PAM admins."
        },
        "password": {
            "allow_view": true,
            "view_mode": "complete",
            "require_reason": false,
            "require_approval": true,
            "approvals_required": 1,
            "disapprovals_to_cancel": 1,
            "approval_in_levels": true,
            "allow_emergency_access": true,
            "allow_change_expiration": true,
            "change_expiration_minutes": 30,
            "require_approval_days": false,
            "approval_days": [],
            "approval_times": [],
            "approval_custom_times": []
        },
        "session": {
            "allow_start": true,
            "block_during_freezing": false,
            "require_reason": true,
            "require_approval": true,
            "approvals_required": 1,
            "disapprovals_to_cancel": 1,
            "approval_in_levels": true,
            "allow_emergency_access": true,
            "require_change_id": true,
            "require_approval_days": true,
            "approval_days": ["all"],
            "approval_times": ["all"],
            "approval_custom_times": []
        },
        "approvers_config": {
            "governance_id_required": true,
            "always_add_user_manager": true
        },
        "criteria": {
            "site_ids": [1],
            "device_type_ids": [3],
            "credential_type_ids": [5],
            "devices": [],
            "products": [],
            "usernames": [],
            "additional_information": [],
            "device_tags": ["prod"],
            "credential_tags": ["finance"]
        },
        "access_limitation": {
            "days": ["all"],
            "times": ["all"],
            "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

Field	Type	Description
`data`	object	The access policy.
`data.id`	integer	Unique identification code of the access policy, assigned by Segura®.
`data.access_policy`	object	Core attributes of the access policy.
`data.access_policy.name`	string	Name of the access policy.
`data.access_policy.active`	boolean	Indicates whether the policy is active. Changed through POST \| Activate access policy and POST \| Deactivate access policy.
`data.access_policy.description`	string	Description of the access policy. Returns `null` when not provided.

`password`

Field	Type	Description
→`allow_view`	boolean	Indicates whether password viewing is enabled.
→`view_mode`	string	How much of the password is revealed. Possible values: `complete`, `first_part`, `second_part`.
→`require_reason`	boolean	Indicates whether a justification is required.
→`require_approval`	boolean	Indicates whether approval is required before access is granted.
→`approvals_required`	number	Number of approvals needed to grant access.
→`disapprovals_to_cancel`	number	Number of rejections that cancel the request.
→`approval_in_levels`	boolean	Indicates whether approval by levels is enabled.
→`allow_emergency_access`	boolean	Indicates whether emergency access is enabled.
→`allow_change_expiration`	boolean	Indicates whether the access expiration can be changed.
→`change_expiration_minutes`	number	Maximum expiration time, in minutes.
→`require_approval_days`	boolean	Indicates whether approval is restricted to specific days.
→`approval_days`	array[string]	Days on which approval is accepted. Returns an empty array when not configured.
→`approval_times`	array[string]	Time windows in which approval is accepted. Returns an empty array when not configured.
→`approval_custom_times`	array[object]	Custom approval time windows. Returns an empty array when not configured.

`session`

Field	Type	Description
→`allow_start`	boolean	Indicates whether session start is enabled.
→`block_during_freezing`	boolean	Indicates whether sessions are blocked during a freezing window.
→`require_reason`	boolean	Indicates whether a justification is required.
→`require_approval`	boolean	Indicates whether approval is required before the session starts.
→`approvals_required`	number	Number of approvals needed to start the session.
→`disapprovals_to_cancel`	number	Number of rejections that cancel the request.
→`approval_in_levels`	boolean	Indicates whether approval by levels is enabled.
→`allow_emergency_access`	boolean	Indicates whether emergency access is enabled.
→`require_change_id`	boolean	Indicates whether a Change Audit ID is required to start the session.
→`require_approval_days`	boolean	Indicates whether approval is restricted to specific days.
→`approval_days`	array[string]	Days on which approval is accepted. Returns an empty array when not configured.
→`approval_times`	array[string]	Time windows in which approval is accepted. Returns an empty array when not configured.
→`approval_custom_times`	array[object]	Custom approval time windows. Returns an empty array when not configured.

`approvers_config`

Field	Type	Description
→`governance_id_required`	boolean	Indicates whether a Governance ID is required on the access request.
→`always_add_user_manager`	boolean	Indicates whether the user's manager is automatically added as an approver.

`criteria`

Criteria are combined with AND logic; values inside each array are combined with OR logic. An empty array means the criterion isn't applied.

Field	Type	Description
→`site_ids`	array[number]	Identification codes of the sites covered by the policy.
→`device_type_ids`	array[number]	Identification codes of the device types covered by the policy.
→`credential_type_ids`	array[number]	Identification codes of the credential types covered by the policy.
→`devices`	array[string]	Hostnames of the devices covered by the policy.
→`products`	array[string]	Products or models covered by the policy.
→`usernames`	array[string]	Usernames covered by the policy.
→`additional_information`	array[string]	Additional information values covered by the policy.
→`device_tags`	array[string]	Device tags covered by the policy.
→`credential_tags`	array[string]	Credential tags covered by the policy.

Info

Filtering by device manufacturer isn't available through this API, so no manufacturer criterion is returned. The web interface does offer this criterion.

`access_limitation`

Field	Type	Description
→`days`	array[string]	Days on which access is allowed. Possible values: `all`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`.
→`times`	array[string]	Time windows in which access is allowed. Possible values: `all`, `00:00-04:00`, `04:00-08:00`, `08:00-12:00`, `12:00-16:00`, `16:00-20:00`, `20:00-00:00`.
→`custom_times`	array[object]	Custom time windows in which access is allowed. Returns an empty array when not configured.
→`period_start`	datetime	Start of the period in which the policy applies. Returns `null` when there's no restriction.
→`period_end`	datetime	End of the period in which the policy applies. Returns `null` when there's no restriction.

`meta`

Field	Type	Description
`meta`	object	Resource metadata.
`meta.links`	object	Navigation links for the resource.
`meta.links.self`	string	Path of the access policy.
`meta.actions`	object	Actions available for the policy in its current state. An active policy offers `deactivate`; an inactive policy offers `activate`.
`meta.actions.deactivate`	string	Path used to deactivate the policy. Returned when the policy is active.

Errors

HTTP code	Message	Possible cause	Solution
`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 read 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.
`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.