---
title: "POST | Create access policy"
slug: "api-v2-post-create-access-policy"
updated: 2026-11-09T19:11:50Z
published: 2026-11-09T19:11:50Z
canonical: "docs.senhasegura.io/api-v2-post-create-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.

# POST | Create access policy

## Description

Create an access policy in PAM Core. A single request defines the policy name, its password and session rules, its approver behavior, the criteria that determine which credentials and devices the policy covers, and its access time limitations.

---

## 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](/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 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

`POST` `/api/v2/pam/access-policies`

### Headers

| Header | Required | Description |
| --- | --- | --- |
| `Content-Type` | Yes | Must be `application/json`. |
| `Idempotency-Key` | No | Client-generated UUID that lets the request be retried safely without creating duplicate policies. |

### Request body

| 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. Returns `null` when not provided. |
| `password` | object | — | Rules for password access. See [Password](/v4-2/docs/api-v2-post-create-access-policy#password). |
| `session` | object | — | Rules for session access. See [Session](/v4-2/docs/api-v2-post-create-access-policy#session). |
| `approvers_config` | object | — | Approver behavior. See [Approvers config](/v4-2/docs/api-v2-post-create-access-policy#approvers-config). |
| `criteria` | object | — | Rules that determine which resources the policy covers. See [Criteria](/v4-2/docs/api-v2-post-create-access-policy#criteria). |
| `access_limitation` | object | — | Time restrictions applied to the policy. See [Access limitation](/v4-2/docs/api-v2-post-create-access-policy#access-limitation). |

Info

The `active` state can't be set here. A policy is activated and deactivated 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).

#### Password

| Field | Type | Description |
| --- | --- | --- |
| `password.allow_view` | boolean | Enables password viewing. |
| `password.view_mode` | string | How much of the password is revealed. Allowed values: `complete`, `first_part`, `second_part`. |
| `password.require_reason` | boolean | Requires the user to provide a justification. |
| `password.require_approval` | boolean | Requires approval before access is granted. |
| `password.approvals_required` | number | Number of approvals needed to grant access. |
| `password.disapprovals_to_cancel` | number | Number of rejections that cancel the request. |
| `password.approval_in_levels` | boolean | Enables approval by levels. |
| `password.allow_emergency_access` | boolean | Enables emergency access. |
| `password.allow_change_expiration` | boolean | Allows the access expiration to be changed. |
| `password.change_expiration_minutes` | number | Maximum expiration time, in minutes. |
| `password.require_approval_days` | boolean | Restricts approval to specific days. |
| `password.approval_days` | array[string] | Days on which approval is accepted. |
| `password.approval_times` | array[string] | Time windows in which approval is accepted. |
| `password.approval_custom_times` | array[object] | Custom approval time windows. |

#### Session

| Field | Type | Description |
| --- | --- | --- |
| `session.allow_start` | boolean | Enables session start. |
| `session.block_during_freezing` | boolean | Blocks sessions during a freezing window. |
| `session.require_reason` | boolean | Requires the user to provide a justification. |
| `session.require_approval` | boolean | Requires approval before the session starts. |
| `session.approvals_required` | number | Number of approvals needed to start the session. |
| `session.disapprovals_to_cancel` | number | Number of rejections that cancel the request. |
| `session.approval_in_levels` | boolean | Enables approval by levels. |
| `session.allow_emergency_access` | boolean | Enables emergency access. |
| `session.require_change_id` | boolean | Requires a Change Audit ID to start the session. |
| `session.require_approval_days` | boolean | Restricts approval to specific days. |
| `session.approval_days` | array[string] | Days on which approval is accepted. |
| `session.approval_times` | array[string] | Time windows in which approval is accepted. |
| `session.approval_custom_times` | array[object] | Custom approval time windows. |

#### Approvers config

| Field | Type | Description |
| --- | --- | --- |
| `approvers_config.governance_id_required` | boolean | Requires a Governance ID on the access request. |
| `approvers_config.always_add_user_manager` | boolean | Automatically adds the user's manager as an approver. |

#### Criteria

The `criteria` object holds the rules that determine which resources the policy covers. Criteria are combined with AND logic; values inside each array are combined with OR logic. An empty array disables that criterion.

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

Info

Filtering by device manufacturer isn't available in this version of the API. The web interface does offer this criterion, so policies that depend on it can't be created or edited through the API.

#### Access limitation

| Field | Type | Description |
| --- | --- | --- |
| `access_limitation.days` | array[string] | Days on which access is allowed. Allowed values: `all`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`. |
| `access_limitation.times` | array[string] | Time windows in which access is allowed. Allowed 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`. |
| `access_limitation.custom_times` | array[object] | Custom time windows in which access is allowed. |
| `access_limitation.period_start` | datetime | Start of the period in which the policy applies. `null` means no restriction. |
| `access_limitation.period_end` | datetime | End of the period in which the policy applies. `null` means no restriction. |

---

### Example request

`POST` `{{url}}/api/v2/pam/access-policies`

#### Body

```
{
    "name": "PAM Administrators",
    "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
    },
    "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"]
    },
    "approvers_config": {
        "governance_id_required": true,
        "always_add_user_manager": true
    },
    "criteria": {
        "site_ids": [1],
        "device_type_ids": [3],
        "credential_type_ids": [5],
        "device_tags": ["prod"],
        "credential_tags": ["finance"]
    },
    "access_limitation": {
        "days": ["all"],
        "times": ["all"],
        "period_start": null,
        "period_end": null
    }
}
```

---

## Response

```
HTTP/1.1 201 Created
Location: /api/v2/pam/access-policies/3001
ETag: "v1"
```

The `Location` header holds the path of the created policy and the `ETag` header holds its current version. Keep the `ETag` value, [PUT | Update access policy](/v4-2/docs/api-v2-put-update-access-policy), [PATCH | Partially update access policy](/v4-2/docs/api-v2-patch-update-access-policy), and [DELETE | Delete access policy](/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 created 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. |
| `data.access_policy.description` | string | Description of the access policy. Returns `null` when not provided. |
| `data.password` | object | Password access rules. Fields match the request body, with unset arrays returned as empty. |
| `data.session` | object | Session access rules. Fields match the request body, with unset arrays returned as empty. |
| `data.approvers_config` | object | Approver behavior. Fields match the request body. |
| `data.criteria` | object | Rules covered by the policy. All nine criteria are returned, with unset ones as empty arrays. |
| `data.access_limitation` | object | Time restrictions applied to the policy. |
| `meta` | object | Resource metadata. |
| `meta.links` | object | Navigation links for the created resource. |
| `meta.links.self` | string | Path of the created access policy. |
| `meta.actions` | object | Actions available for the policy in its current state. A policy created as active offers `deactivate`. |
| `meta.actions.deactivate` | string | Path used to deactivate the policy. |

---

## 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 create access policies. | Ask the administrator to check the **Access Policy (V2)** authorization and the **PAM resource permission** in A2A, then generate a new token. |
| `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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).