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:

• entries (or what to check)—the lists of the successions of characters or regular expressions which the rule will compare against the source or destination number, or the text message. You can specify several entries even for a single rule, or use regular expressions for a greater coverage by a single entry. Examples of entries: 1516, .*516, 1516.*.

• field (or where to check)—the field from the call or the text message where the system will look for the matches to the entries. Examples of the field attribute values: calling, called (for calls), from, to, message (for text messages).

• operation (or how to treat entries)—the way that the rule will treat the values of the entries:
  • whether the entries will be matched exactly (no other character can be added or the ones present in the entries can be omitted),
  • or the entry should match only the part at the beginning of, for example, the phone number,
  • or the entry is a regular expression which can match various phone numbers or messages.
    Examples of the operation attribute values: exact, prefix, regexp.
• quantifier (or how to treat matches)—the way the system treats the matches:
  • whether all the entries should match,
  • or at least one of the entries,
  • or none of the entries should match the phone number or message.
    Examples of the quantifier attribute values: all, any, none.

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

• The name attribute is simply a human-readable name used to distinguish the rule from other such rules for the partners who use them.
• The rule_sid attribute is the rule secure identifier used to unambiguously identify the rule by the system. The rule secure ID is also used to form access control lists.
• And the read_only attribute (either true or false) defines whether the rule can be edited or not by the partners. For the rules created by the parent partner this attribute is automatically set to true for all sub-partners. This prevents all the sub-partner accounts from modifying the rules. Such rules will be visible in the parent_acl attribute of the Partner object and will override any of the rules which the sub-partner sets up.

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:

• Parent partner level
• Partner level
• Trunk group level
• Trunk level

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:

• access_control_rules is the list of the secure IDs of the access control rules which you created earlier.

• direction is the direction of the voice calls or text messages for which the rules are active. You can activate the rules for the outbound or inbound communications, or both directions at once, or for the communications without any direction specified.

• sms_action_false is the action which the system will apply to the text messages if the access control rules from the list are not triggered. Depending on this attribute value, the system will either accept or reject the text message which does not match the rules:
  • set this to accept to explicitly accept the text messages that do not match the rules;
  • set this to reject to explicitly reject the text messages that do not match the rules;
  • or leave this as null to ignore the unmatched rules for the text messages.
• sms_action_true is the action which the system will apply to the text messages if the access control rules from the list are triggered. Depending on this attribute value, the system will either accept or reject the text message which matches the rules:
  • set this to accept to explicitly accept the text messages that match the rules;
  • set this to reject to explicitly reject the text messages that match the rules;
  • or leave this as null to ignore the matched rules for the text messages.

• voice_action_false is the action which the system will apply to the voice calls if the access control rules from the list are not triggered. Depending on this attribute value, the system will either accept or reject the voice call which does not match the rules:
  • set this to accept to explicitly accept the voice calls that do not match the rules;
  • set this to reject403 or reject503 to explicitly reject the voice calls that do not match the rules with a 403 or 503 status code;
  • or leave this as null to ignore the unmatched rules for the voice calls;
  • at the Trunk level, you can also set this attribute to skip to treat the trunk as if it does not exist at all and send the call on to the next trunk.
• voice_action_true is the action which the system will apply to the voice calls if the access control rules from the list are triggered. Depending on this attribute value, the system will either accept or reject the voice call which matches the rules:
  • set this to accept to explicitly accept the voice calls that match the rules;
  • set this to reject403 or reject503 to explicitly reject the voice calls that match the rules with a 403 or 503 status code;
  • or leave this as null to ignore the matched rules for the voice calls;
  • at the Trunk level, you can also set this attribute to skip to treat the trunk as if it does not exist at all and send the call on to the next trunk.

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:

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:

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:

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:

• Getting Started
• How It Works
• CarrierX Endpoints
• Trunk Groups and Trunks
• Prefix Routing
• Transformations
• STIR/SHAKEN
• Storing Files with CarrierX
• Send Push Notifications to Devices
• Lookup Phone Numbers and IP Addresses
• Using OAuth Tokens