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 the partner account, with a trunk group or with a trunk.

Access control lists can be created and applied at any of the following levels:

The order of the rules, in which you add them to the lists, is important. The rules are checked one by one in the order they appear in the lists. For each ACL level (trunk, trunk group, partner, etc.) the rules will be executed in the order they have been added to the list, and actions will be taken in the same order.

This means that if the first rule, which is triggered, is an accept then the call/message passes that level successfully even if there are other rules later at that level that would reject such call/message. A reject can still happen at another level, but within each level the rules are evaluated in order one after another until the first match is found and the corresponding ACR action is triggered.

The system also observes the following order of checking ACLs at different levels: first, it checks the trunk level access control lists; then the trunk group level ACLs; the partner level ACLs; and, finally, the parent partner level ACLs.

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:

Check all the access control rules currently effective

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 Level Access Control Lists

Access control lists assigned at the trunk level are applied to all the endpoints associated with the affected trunk. The main difference between the ACLs at the Trunk level is that the Trunk Group is usually set up to either completely accept or reject certain calls meeting particular criteria, while at the Trunk level you can set up a certain Trunk to skip the call and pass it to another Trunk, which can process that call. For example, this allows you to set up a particular Trunk to get only one certain type of traffic and ignore all the other types.

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

Access Control Lists Trunk

This can be done with the following PATCH request:

curl -X PATCH \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks/aed1c137-8cbf-417c-8c41-e181f425826b' \
-H 'Content-Type: application/json' \
--data-binary '{"acls":[{"access_control_rules":["dafd993d-0e99-4af9-b8fc-436fb01b0bbe","6fd782fa-c80b-4299-9b91-78797eb392e1","15c71d02-04b1-451f-a267-25c1046f4e06"],"direction":"outbound","sms_action_false":null,"sms_action_true":null,"voice_action_false":null,"voice_action_true":"skip"}]}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "acls": [
        {
            "access_control_rules": [
                "dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
                "6fd782fa-c80b-4299-9b91-78797eb392e1",
                "15c71d02-04b1-451f-a267-25c1046f4e06"
            ],
            "direction": "outbound",
            "sms_action_false": null,
            "sms_action_true": null,
            "voice_action_false": null,
            "voice_action_true": "skip"
        }
    ],
    "allow_forward": "disabled",
    "allow_transfer": false,
    "asn_mode": "disable",
    "call_type": "regular",
    "codec": null,
    "endpoint_sid": "38d92b6d-ad0e-460a-9192-276da5e8badf",
    "in_capacity": 0,
    "in_identity_format": "passthrough",
    "in_identity_mode": "passthrough",
    "in_rfc_4694_mode": "cut_all",
    "location_sid": null,
    "name": "Outbound test trunk",
    "out_capacity": 0,
    "out_identity_mode": "passthrough",
    "out_rfc_4694_mode": "cut_all"
    "out_sip_ringing_max_ttl": 180,
    "priority": 0,
    "relay_sip_headers": [],
    "transformations": [],
    "trunk_sid": "23ee18be-4db2-448c-a902-3a8d648eca39",
    "weight": 1,
}

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"
        }
    ],
    "external_handlers": [],
    "hard_failure_codes": "408;",
    "hard_failure_cooldown": 120,
    "hard_failure_interval": 60,
    "hard_failure_last_resort": "first",
    "hard_failure_threshold": 3,
    "name": "New Trunk Group",
    "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
    "routing_data": null,
    "routing_type": "failover",
    "sip_options_locations": [],
    "sip_options_threshold": 3,
    "soft_failure_codes": "408;",
    "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",
    "daily_spending_limit": "500",
    "daily_spent_amount": "0",
    "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:

How It Works

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