When your customers have purchased elastic tokens, the budget for the tokens may have been provided by specific teams, disciplines, divisions or projects. Your customer will therefore need to be able to control which user of device, or for what purpose, the tokens are consumed. This will ensure correct and proportionate consumption of the allocated budget.
The Dynamic Monetization Elastic Access Rules of Access APIs allow your customers to define and enforce access control policies for the consumption of tokens from elastic line items in your Dynamic Monetization environment. The rules determine by who or where tokens can be consumed, based on specific conditions.
Conditions are logical expressions that evaluate attributes of an access request—defined in a field in the access request called a requester dictionary—and compare them against allowed values. They help you define when a rule should apply.
A simple condition specifies a list of values that should either be IN or NOT in the requester dictionary. A complex condition combines a number of simple conditions using AND or OR.
Conditions are defined at the level of a Dynamic Monetization instance and can therefore be re-used in any line item found in the instance.
| Key API Endpoints | Actions |
|---|---|
| GET /v1.0/instances/{instanceId}/conditions | Retrieve all conditions defined for a specific instance. |
| POST /v1.0/instances/{instanceId}/conditions | Create new conditions that describe the criteria under which access rules should be triggered. |
| PATCH /v1.0/instances/{instanceId}/conditions | Modify existing conditions. |
| DELETE /v1.0/instances/{instanceId}/conditions | Remove all conditions from an instance. This is only allowed if no actions are referencing them. |
| DELETE /v1.0/instances/{instanceId}/conditions/{conditionId} | Remove a specific condition from an instance. This is only allowed if no actions are referencing it. |
Actions define what happens when a condition is met. For example, you can ALLOW or DENY access, and optionally allocate a specific number of tokens when access is allowed. The actions are defined in an ordered list, and the effects of the actions are applied in the order given by the list. Once an action is applied, the remainder of the list is ignored; there is no “follow through” to apply a sequence of actions to the request.
DENY can be configured
with a specified condition, to prevent certain requesters or groups of requesters consuming tokens from the line items.
with no condition to create a default action. This is useful to prevent consumption of tokens from the line item until the rest of the actions have been configured. A default DENY can also be placed at the end of the list of actions to specify what must be done with a request if no condition is met.
ALLOW can be configured
with a specified condition and a specified allocation. This ensures certain requesters or groups of requesters can consume tokens, up to the limit given by the allocation.
with a specified condition but no allocation. This sets up a “privileged” requester who can consume tokens from the line item without limit.
with no condition or allocation. This is a default ALLOW action for the line item, which can be placed at the end of the actions allowing a requester not matching any condition to be able to consume from the line item without limit.
A set of actions should be set up with either a default ALLOW, or a default DENY, at the end of the list.
It is advisable for the allocations in a line item to total the number of tokens in the line item. Dynamic Monetization does not enforce this however:
If the total of the allocations is less than the quantity entitled by the line item then there will be unallocated tokens remaining, which could be consumed by requesters benefiting from a default ALLOW action.
If the total of the allocations is greater than the quantity entitled by the line item then as the entitled quantity approaches complete consumption, some requesters may not be able to access their entire allocation
Increasing or decreasing the entitled quantity in a line item can lead to either of the above effects
Using a default ALLOW, or an ALLOW without an allocation, can cause tokens to be consumed from the line item so that, as the entitled quantity approaches complete consumption, some requesters may not be able to access their entire allocation
| Key API Endpoints | Actions |
|---|---|
| POST /v1.0/instances/{instanceId}/line-items/{lineItemId}/actions | Define an ordered list of actions for a line item, each linked to a condition. |
| PUT /v1.0/instances/{instanceId}/line-items/{lineItemId}/actions | Modify the ordered list of actions for a line item, each linked to a condition. |
| GET /v1.0/instances/{instanceId}/line-items/{lineItemId}/actions | Retrieve the current set of actions configured for an instance for a specified line item. |
| GET /v1.0/instances/{instanceId}/line-items/actions | Retrieve all actions for all Elastic Access line items of a specific instance. |
| DELETE /v1.0/instances/{instanceId}/line-items/{lineItemId}/actions | Remove all actions from a line item. |
Implementing rules of access typically involves three key stages:
- Defining Conditions—Specify the criteria that must be met (for example, user is in a specific region or product is of a certain type).
- Assigning Actions—Link those conditions to actions that determine whether access is allowed and how many tokens are consumed.
- Dynamic Enforcement—When an access request is made, the system evaluates the conditions and executes the corresponding actions.
Once actions have been set up, a decision has been made about who is permitted to consume tokens. If the intention is to restrict consumption exclusively to a limited set of clients, then it is important to restrict access as soon as possible after the line item has been created. This can be done by making the first rule created a "default deny" rule, which is an action with no condition (so that it is always applied) and the DENY action.
After this, add the other actions required before the default deny in the ordered list of actions.
Once consumption has started, two things could be modified:
- The line item entitled count
- The allocations defined in the actions
It is important to understand the consequences of making these changes.
When an allocation is close to or at its limit it is not recommended:
- to reduce a line-item quantity
- to increase allocation quantities
If the line-item count is decreased, or the allocations increased, then there will be fewer "free" tokens for general consumption. It is possible to increase the allocations so that they sum to a total greater than the tokens available in the line item. This will create contention (or "competition") between client requests satisfying different conditions.
The situation will be particularly acute when the allocations are completely, or almost completely consumed. If an allocation is reduced to a value lower than the current total consumed for that allocation, then
- New access requests will not be fulfilled from the line item.
- Any in-progress sessions will not be able to increase the items requested (but if rollbackOnDeny is true, then the session will continue to use what was previously requested).
- An in-progress session will be able to reduce the items requested; a partial refund of tokens will be made, but if the refund is small then the used count will still exceed the allocation.
The consequences of these changes are confusing, and so when an allocation is close to or at its limit it is not recommended to:
- reduce a line-item quantity
- increase allocation quantities
If a line-item count is increased, or the allocations decreased, then the number of available tokens for "free access" is increased. Unless a default rule is in place, these will be consumed by any request not matched by a condition. If this is not the intention, then once again a default DENY should be set up.
For a tutorial walking you through the steps for creating conditions and actions, see Controlling Access with Conditions and Actions.