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.
A valid OAuth 2.0 access token. For more information, access 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.
`session`	object	—	Rules for session access. See Session.
`approvers_config`	object	—	Approver behavior. See Approvers config.
`criteria`	object	—	Rules that determine which resources the policy covers. See Criteria.
`access_limitation`	object	—	Time restrictions applied to the policy. See Access limitation.

Info

The active state can't be set here. A policy is activated and deactivated through POST | Activate access policy and 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, PATCH | Partially update access policy, and DELETE | 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.