Access Control

Access control allows CarrierX partners to set up additional rules for inbound and outbound calls and text messages, group these rules into lists, and apply them on either partner or trunk group levels.

Why Use Access Control?

There can be various reasons why you would want to use access control rules.

For example, you can apply the access control rules to outbound communications to prevent either calling or sending text messages to specific (e.g., paid) numbers. Or you can allow sending calls to one phone number only and rejecting the calls to all other phone numbers. Or you want to disallow sending (or receiving) all text messages which contain a certain text.

You can do all this if you create one or more access control rules, group them into lists, and apply them either to the whole account (on the partner level) or to a specific trunk group only (to the selected endpoints associated with this trunk group).

You can flexibly specify accept and reject actions separately for each type of communication: both for voice calls and text messages,—when the rule is either matched or not.

Access Control Rules

Before you can apply any of the access control lists to calls or text messages, you need to create access control rules (or ACRs).

Structure

An access control rule looks like the following:

{
    "entries": [
        "1800",
        "1615"
    ],
    "field": "called",
    "name": "N/A",
    "operation": "prefix",
    "quantifier": "any",
    "read_only": false,
    "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}

As you can see, each access control rule includes the following main attributes:

Additionally, the rules include the name, rule_sid, and read_only attributes.

Refer to the section below for examples of various access control rules.

Examples

The following examples show sample access control rules with various attributes.

Example #1

Example #2

Example #3

Access Control Lists

Access control rules do not do anything on their own. You can only use them to check for matches against the entries.

For these rules to work, you must group them into access control lists and associate with either the partner account or with a trunk group.

Structure

Access control lists look like the following:

{
    "access_control_rules": [
        "dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
        "6fd782fa-c80b-4299-9b91-78797eb392e1"
    ],
    "direction": "outbound",
    "sms_action_false": null,
    "sms_action_true": null,
    "voice_action_false": null,
    "voice_action_true": "reject503"
}

As you can see, each access control list includes the following main attributes:

You can check all the currently effective access control rules.

Use the following request for calls:

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/effective_acl/calls' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

And the following request for the currently effective ACLs for text messages:

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/effective_acl/sms' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The requests will return the effective access control lists for calls and text messages and their execution order (the rules in the lists will be triggered one by one from the top layer to the lower one).

Trunk Group Level Access Control Lists

Access control lists assigned at the trunk group level are applied to all the endpoints associated with the affected trunk group.

Use the acls attribute of the Trunk Group object to create the access control lists associated with the trunk group:

Access Control Lists Trunk Group

This can be done with the following PATCH request:

curl -X PATCH \
'https://api.carrierx.com/core/v2/trunk_groups/c7eae0b4-5eda-4964-8998-d514903b4af0' \
-H 'Content-Type: application/json' \
--data-binary '{"acls":[{"access_control_rules":["dafd993d-0e99-4af9-b8fc-436fb01b0bbe","6fd782fa-c80b-4299-9b91-78797eb392e1"],"direction":"outbound","sms_action_false":null,"sms_action_true":null,"voice_action_false":null,"voice_action_true":"reject503"}]}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The successful request will return an updated Trunk Group object with the access control lists assigned:

{
    "acls": [
        {
            "access_control_rules": [
                "dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
                "6fd782fa-c80b-4299-9b91-78797eb392e1"
            ],
            "direction": "outbound",
            "sms_action_false": null,
            "sms_action_true": null,
            "voice_action_false": null,
            "voice_action_true": "reject503"
        }
    ],
    "name": "New Trunk Group",
    "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
    "routing_data": null,
    "routing_type": "failover",
    "soft_failure_codes": "408;",
    "soft_failure_cooldown": 120,
    "transformations": [],
    "trunk_group_sid": "503167ea-b8a5-4a5d-97e3-d684884da1d8"
}

Partner Level Access Control Lists

Access control lists assigned at the partner level are applied to all the calls and text messages sent and received by the partner account.

Use the acls attribute of the Partner object to create the access control lists associated with the partner account. The parent partner account can additionally assign access control rules to the current Partner object using the parent_assigned_acls attribute:

Access Control Lists

This can be done with the following PATCH request:

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-H 'Content-Type: application/json' \
--data-binary '{"acls":[{"access_control_rules":["dafd993d-0e99-4af9-b8fc-436fb01b0bbe","6fd782fa-c80b-4299-9b91-78797eb392e1"],"direction":"outbound","sms_action_false":null,"sms_action_true":null,"voice_action_false":null,"voice_action_true":"reject503"}]}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The successful request will return an updated Partner object with the access control lists assigned:

{
    "acls": [
        {
            "access_control_rules": [
                "dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
                "6fd782fa-c80b-4299-9b91-78797eb392e1"
            ],
            "direction": "outbound",
            "sms_action_false": null,
            "sms_action_true": null,
            "voice_action_false": null,
            "voice_action_true": "reject503"
        }
    ],
    "address1": "4300 E Pacific Coast Hwy",
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "351.52",
    "billing_email": "example@example.com",
    "callbacks": {},
    "charge_at": "20",
    "city": null,
    "company_name": "CarrierX",
    "country_code": "USA",
    "date_created": "2018-09-20T21:34:55.000Z",
    "display_id": "CX72521509",
    "login": "example",
    "name": "John Smith",
    "owner_email": "example@example.com",
    "parent_assigned_acls": [],
    "parent_sid": "ac38616e-d2e3-4cd6-99ae-b6658f0728b6",
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0",
    "payment_type": "prepay",
    "phonenumber": "15162065574",
    "prepay_amount": "100",
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "tech_email": "example@example.com",
    "transformations": [],
    "zip": "90804"
}

Examples

Further Reading

Access Control List and Access Control Rule Objects API Reference

Refer to the Access Control List and Access Control Rule objects API reference to get the complete list of their attributes and methods used with them:

Access Control List Object

Access Control Rule Object

How It Works

Read the following articles to get a better understanding of how things work in CarrierX: