Skip to main content

Users & Roles Governance

Vasyl MartyniukAbout 2 min

Note!

The "Identity Governance" service has to be enabled on the AAM "Settings" page for these endpoints to work.

Get All Rules

Get the list of all identity governance rules for given access level.

Endpoint

GET /aam/v2/service/identity-governance

Parameters

ParamsDescription
access_levelRequired. Can be either "role", "user", "visitor" or "default".
role_idConditionally required. The option is required if the access_level is "role".
user_idConditionally required. The option is required if the access_level is "user".
Response Sample
[
    {
        "id": 1103614957,
        "is_inherited": false,
        "rule_type": "user_role",
        "permissions": [
            {
                "permission": "edit_user",
                "effect": "deny"
            },
            {
                "permission": "delete_user",
                "effect": "deny"
            }
        ],
        "role_slug": "author",
        "display_name": "Authors"
    }
]

Get Single Rule

Endpoint

GET /aam/v2/service/identity-governance/<id>

Parameters

ParamsDescription
idRequired. The unique rule ID.
access_levelRequired. Can be either "role", "user", "visitor" or "default".
role_idConditionally required. The option is required if the access_level is "role".
user_idConditionally required. The option is required if the access_level is "user".
Response Sample
{
    "id": 1103614957,
    "is_inherited": false,
    "rule_type": "user_role",
    "permissions": [
        {
            "permission": "edit_user",
            "effect": "deny"
        },
        {
            "permission": "delete_user",
            "effect": "deny"
        }
    ],
    "role_slug": "author"
}

Create New Rule

Endpoint

POST /aam/v2/service/identity-governance

Parameters

ParamsDescription
access_levelRequired. Can be either "role", "user", "visitor" or "default".
role_idConditionally required. The option is required if the access_level is "role".
user_idConditionally required. The option is required if the access_level is "user".
rule_typeRequired. Rule type. The allowed values are "role", "user_role", "role_level", "user", "user_level".
user_listConditionally required. The array of user identifiers. This has to be a array of scalar values where each item is either integer user ID, user login or user email address. The field is required if the rule_type equals to user.
role_listConditionally required. The array of role slugs. The field is required if the rule_type equals to role or user_role.
level_listConditionally required. The array of integer values, typically between 0 and 10. The field is required if the rule_type equals to role_level or user_level.
permissionsRequired. The array of permissions where each item is an object with permission and effect properties. Refer to Permission model for details.
Response Sample
[
    {
        "id": 798405660,
        "is_inherited": false,
        "rule_type": "user_role",
        "permissions": [
            {
                "permission": "change_user_password",
                "effect": "deny"
            },
            {
                "permission": "delete_user",
                "effect": "deny"
            }
        ],
        "role_slug": "subscriber"
    }
]

Update Existing Rule

Endpoint

PATCH /aam/v2/service/identity-governance/<id>

Parameters

ParamsDescription
idRequired. The unique rule ID.
access_levelRequired. Can be either "role", "user", "visitor" or "default".
role_idConditionally required. The option is required if the access_level is "role".
user_idConditionally required. The option is required if the access_level is "user".
rule_typeRequired. Rule type. The allowed values are "role", "user_role", "role_level", "user", "user_level".
user_loginConditionally required. User identifiers. This has to be either integer user ID, user login or user email address. The field is required if the rule_type equals to user.
role_listConditionally required. Role slug. The field is required if the rule_type equals to role or user_role.
level_listConditionally required. An integer value, typically between 0 and 10. The field is required if the rule_type equals to role_level or user_level.
permissionsRequired. The array of permissions where each item is an object with permission and effect properties. Refer to Permission model for details.
Response Sample
{
    "id": 798405660,
    "is_inherited": false,
    "rule_type": "user_role",
    "permissions": [
        {
            "permission": "change_user_password",
            "effect": "deny"
        },
        {
            "permission": "delete_user",
            "effect": "deny"
        }
    ],
    "role_slug": "subscriber"
}

Delete Rule

Endpoint

DELETE /aam/v2/service/identity-governance/<id>

Parameters

ParamsDescription
idRequired. The unique rule ID.
access_levelRequired. Can be either "role", "user", "visitor" or "default".
role_idConditionally required. The option is required if the access_level is "role".
user_idConditionally required. The option is required if the access_level is "user".
Response Sample
{
    "success": true
}

Reset All Rules

Endpoint

DELETE /aam/v2/service/identity-governance

Parameters

ParamsDescription
access_levelRequired. Can be either "role", "user", "visitor" or "default".
role_idConditionally required. The option is required if the access_level is "role".
user_idConditionally required. The option is required if the access_level is "user".
Response Sample
[]