---
title: "GET | List an access policy by [id]"
slug: "api-v2-get-list-an-access-policy"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-get-list-an-access-policy"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v4-2/docs/api-v2-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](/v4-2/docs/how-to-manage-authorizations-in-a2a).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).
- The identification code of the access policy, returned by [POST | Create access policy](/v4-2/docs/api-v2-post-create-access-policy) or by [GET | List all access policies](/v4-2/docs/api-v2-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](/v4-2/docs/api-v2-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](/v4-2/docs/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]](/v4-2/docs/api-v2-put-update-access-policy), [PATCH | Partially update access policy by [id]](/v4-2/docs/api-v2-patch-update-access-policy), and [DELETE | Delete access policy by [id]](/v4-2/docs/api-v2-delete-access-policy) 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](/v4-2/docs/api-v2-post-activate-access-policy) and [POST \| Deactivate access policy](/v4-2/docs/api-v2-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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).