Manage authentication rules

An authentication rule matches incoming calls to an account by the caller’s IP address, CLI, CLD or domains, and can override the account’s tariff and routing group for those calls. Use these methods to provision IP trunks and DIDs from your own system; they do the same as the Authentication Rules screen of an account.

All methods support trusted mode with i_customer.

Authentication rule structure

addAuthRule and updateAuthRule take these fields, getAuthRuleInfo and listAuthRules return them.

Name	Type	Description
i_authentication	int	ID of the rule. Returned, never sent to addAuthRule
i_account	int	Account the matched calls are authenticated to
i_protocol	int	1 SIP, 3 IAX2, 4 Calling Card PIN
remote_ip	string	Remote IP Address: the IP address the call comes from
incoming_cli	string	Incoming CLI/ANI: the caller’s number
incoming_cld	string	Incoming CLD/DNIS: the dialled number. With i_protocol 4 this is the calling card PIN
to_domain	string	To Domain: the domain in the To header
from_domain	string	From Domain: the domain in the From header
cli_translation_rule	string	CLI Tr. Rule: translation rule applied to the CLI of matched calls
cld_translation_rule	string	CLD Tr. Rule: translation rule applied to the CLD of matched calls
max_sessions	int	Max Sessions: maximum simultaneous calls matched by the rule. -1 is unlimited
max_cps	double	Max Calls Per Second: maximum new calls per second. Nil is unlimited
i_tariff	int	Tariff for matched calls. Nil uses the account’s tariff
i_routing_group	int	Routing Group for matched calls. Nil uses the account’s routing group

An empty match field matches anything. incoming_cli and incoming_cld accept patterns such as 4420*. How the switch chooses between overlapping rules is explained in Authentication.

addAuthRule

Adds a rule to an account.

Parameters

Name	Type	Required	Description
i_account	int	yes	ID of the account
i_protocol	int	yes	See the structure
remote_ip	string	one of	At least one of remote_ip, incoming_cli and incoming_cld is required
incoming_cli	string	one of
incoming_cld	string	one of
to_domain, from_domain	string	no
cli_translation_rule, cld_translation_rule	string	no
max_sessions	int	no	Default unlimited
max_cps	double	no	Default unlimited
i_tariff	int	no	Default nil: the account’s tariff
i_routing_group	int	no	Default nil: the account’s routing group

Returns

Name	Type	Description
result	string	OK
i_authentication	int	ID of the new rule

Example

request

call("addAuthRule", {
    "i_account": 3092,
    "i_protocol": 1,
    "remote_ip": "192.0.2.10",
    "cld_translation_rule": "s/^00//",
    "max_cps": 10.0,
})

response

{"result": "OK", "i_authentication": 5521}

updateAuthRule

Changes a rule. Send only the fields you change.

Parameters

Name	Type	Required	Description
i_authentication	int	yes	ID of the rule
any other field	as in the structure	no	New value of a field of the structure, except i_account. Send nil in i_tariff or i_routing_group to use the account’s again

Returns

Name	Type	Description
result	string	OK

Example

request

call("updateAuthRule", {"i_authentication": 5521, "max_sessions": 30, "max_cps": None})

response

{"result": "OK"}

delAuthRule

Deletes a rule.

Parameters

Name	Type	Required	Description
i_authentication	int	yes	ID of the rule

Returns

Name	Type	Description
result	string	OK

Example

request

call("delAuthRule", {"i_authentication": 5521})

response

{"result": "OK"}

getAuthRuleInfo

Returns one rule.

Parameters

Name	Type	Required	Description
i_authentication	int	yes	ID of the rule

Returns

Name	Type	Description
result	string	OK
authrule	struct	The rule, with the fields of the structure

Example

request

call("getAuthRuleInfo", {"i_authentication": 5521})

response

{
    "result": "OK",
    "authrule": {
        "i_authentication": 5521,
        "i_account": 3092,
        "i_protocol": 1,
        "remote_ip": "192.0.2.10",
        "incoming_cli": "",
        "incoming_cld": "",
        "cld_translation_rule": "s/^00//",
        "max_sessions": 30,
        "max_cps": None,
        "i_tariff": None,
        "i_routing_group": None,
        # … the other fields of the structure
    },
}

listAuthRules

Lists rules. All filters are optional.

Parameters

Name	Type	Required	Description
i_account	int	no	Only rules of this account
i_authentication	int	no	Only this rule
i_protocol	int	no	Only rules with this protocol
remote_ip	string	no	Only rules with this remote IP address
offset	int	no	Skip this many rules
limit	int	no	Return at most this many rules

Returns

Name	Type	Description
result	string	OK
authrules	array	Rules, each a struct with the fields of the structure

Example

request

call("listAuthRules", {"i_account": 3092})

response

{
    "result": "OK",
    "authrules": [
        {"i_authentication": 5521, "i_account": 3092, "remote_ip": "192.0.2.10",
         "incoming_cli": "", "incoming_cld": "", "cli_translation_rule": "",
         "cld_translation_rule": "s/^00//"},
    ],
}

Related

• Accounts: the Authentication Rules screen
• Authentication: how the switch matches a call to a rule
• Manage post-authentication rules
• Manage trusted numbers