.. _check_policy:

Method: Check Password Policy
------------------------------

Description
~~~~~~~~~~~

Validates a passphrase against a password policy and returns whether it passes,
along with a human-readable description of the policy rules. Useful for providing
inline feedback in a password field before submitting a form.

The policy to validate against can be specified by ``policyid``, by ``vaultid``
(uses the policy configured on that vault), or omitted (uses the system default
user passphrase policy).

URL Syntax
~~~~~~~~~~

/api/{version}/utils/checkpolicy

HTTP Method
~~~~~~~~~~~

POST

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

200

Parameters
~~~~~~~~~~

+----------------+----------------------------------------------------+----------------+--------+-----------+----------------------------------------+
| Parameter name | Description                                        | Parameter type | Type   | Mandatory | Comment                                |
+================+====================================================+================+========+===========+========================================+
| X-Http-Token   | StoredSafe token                                   | HTTP Header    | String | Yes       |                                        |
+----------------+----------------------------------------------------+----------------+--------+-----------+----------------------------------------+
| passphrase     | The passphrase to validate                         | JSON-encoded   | String | Yes       |                                        |
+----------------+----------------------------------------------------+----------------+--------+-----------+----------------------------------------+
| policyid       | ID of the password policy to validate against      | JSON-encoded   | String | No        | Mutually exclusive with ``vaultid``    |
+----------------+----------------------------------------------------+----------------+--------+-----------+----------------------------------------+
| vaultid        | Use the policy configured on this vault            | JSON-encoded   | String | No        | Mutually exclusive with ``policyid``   |
+----------------+----------------------------------------------------+----------------+--------+-----------+----------------------------------------+
| fieldname      | Label used in rule descriptions (default "Password")| JSON-encoded  | String | No        |                                        |
+----------------+----------------------------------------------------+----------------+--------+-----------+----------------------------------------+

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------+--------------------------------------------------+---------+
| Attribute           | Description                                      | Type    |
+=====================+==================================================+=========+
| CALLINFO.status     | SUCCESS or FAIL                                  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.token      | StoredSafe token to be used in subsequent calls  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                     | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                 | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errorcodes | Number of error codes                            | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.policy_name      | Human-readable name of the policy          | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.policy_id        | Numeric ID of the policy used              | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.passphrase_valid | ``true`` if passphrase meets the policy    | Boolean |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.rules            | Array of rule descriptions                 | Array   |
+---------------------+--------------------------------------------------+---------+

See :ref:`password_policies` for the list of available policy IDs and their rules.

Example
~~~~~~~

Validate a passphrase against policy ID 2 (Normal Quality Password, 10+ chars
mixed case and number).

**Request**

::

    POST /api/1.0/utils/checkpolicy
    X-Http-Token: your_storedsafe_token
    Content-Type: application/json
    {
        "passphrase": "MyP4ssw0rd!",
        "policyid": "2",
        "fieldname": "Passphrase"
    }

**Response (passphrase meets policy)**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "UtilsHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token",
            "policy_name": "Normal Quality Password (10+ chars, mixed case and number)",
            "policy_id": 2,
            "passphrase_valid": true,
            "rules": [
                "Passphrase must be at least 10 characters long"
            ]
        },
        "DATA": { ... },
        "HEADERS": { ... },
        "PARAMS": []
    }

**Response (passphrase does not meet policy)**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "UtilsHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token",
            "policy_name": "Normal Quality Password (10+ chars, mixed case and number)",
            "policy_id": 2,
            "passphrase_valid": false,
            "rules": [
                "Passphrase must be at least 10 characters long"
            ]
        },
        "DATA": { ... },
        "HEADERS": { ... },
        "PARAMS": []
    }