Card Tags Available in Authorization Rule Scoping and ASA Requests

Overview

Beginning Wednesday, October 14th, Authorization Rules will use a single entities parameter to set which cards and accounts a rule applies to. A rule can apply to every card that carries a given tag, so users can target a cohort of cards without maintaining a list of card tokens. ASA requests will also carry the card's tags, so ASA responders can make decisions on the same metadata.

Details

The entities object has an include list of entities the rule applies to and an exclude list of entities it does not apply to. Each entity has a type:

• PROGRAM: the entire card program. Takes no other fields.
• CARD: a single card, identified by token.
• ACCOUNT: a single account, identified by token.
• BUSINESS_ACCOUNT: a single business account, identified by token.
• CARD_TAG: every card whose tags contain key set to value. Keys that start with lithic. are reserved and rejected.

An exclusion overrides an inclusion. A card in exclude is skipped even when its program, its account, or one of its tags is in include.

Creating and Replacing Entities

POST /v2/auth_rules accepts entities on create. PATCH /v2/auth_rules/{auth_rule_token} accepts entities and replaces the rule's existing lists. A missing list is treated as empty, so include must always be present on a replace. Every Auth Rule response includes entities, with both include and exclude.

The following request creates a program-level rule that skips every card tagged risk-level: low:

{
  "name": "Block gambling MCCs",
  "entities": {
    "include": [{ "type": "PROGRAM" }],
    "exclude": [{ "type": "CARD_TAG", "key": "risk-level", "value": "low" }]
  },
  "type": "CONDITIONAL_ACTION",
  "event_stream": "AUTHORIZATION",
  "parameters": {
    "conditions": [
      { "attribute": "MCC", "operation": "IS_ONE_OF", "value": ["7995"] }
    ],
    "action": "DECLINE"
  }
}

Incremental Entity Changes

The new PATCH /v2/auth_rules/{auth_rule_token}/entities endpoint takes an add object and a remove object. Each has its own include and exclude lists. Adding an entity that is already present has no effect. Removing an entity that is not present also has no effect. To move an entity between include and exclude, remove it from one list and add it to the other in the same request.

curl -X PATCH https://api.lithic.com/v2/auth_rules/{auth_rule_token}/entities \
  -H "Authorization: $LITHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add": {
      "include": [{ "type": "CARD_TAG", "key": "risk-level", "value": "high" }]
    },
    "remove": {
      "include": [{ "type": "CARD", "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951" }]
    }
  }'

Listing Rules

GET /v2/auth_rules with scope=CARD and no token also returns rules that include a CARD_TAG entity. A request filtered by card_token returns rules bound to that card's tags, and hides rules that exclude one of the card's tags.

ASA Requests

The card object in ASA requests includes a new tags field with the card's tags. The field is always present, and is an empty object ({}) when the card has no tags.

{
  "card": {
    "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
    "last_four": "1234",
    "memo": "Travel card",
    "spend_limit": 0,
    "spend_limit_duration": "FOREVER",
    "state": "OPEN",
    "type": "VIRTUAL",
    "tags": {
      "risk-level": "high"
    }
  }
}

Release Timeline

Production availability: October 14, 2026

User Impact

This change is additive only. Existing integrations will continue to function without modification. Integrations that read the deprecated scoping fields to determine which cards a rule applies to should read entities, since tag-scoped rules are visible only there.

Deprecated Fields

These fields are deprecated in favor of entities. They remain supported on create, update, and in responses, but a request cannot combine them with entities:

• program_level
• card_tokens
• account_tokens
• business_account_tokens
• excluded_card_tokens
• excluded_account_tokens
• excluded_business_account_tokens

The deprecated card_tokens response field does not list cards that a rule applies to through a CARD_TAG entity.

Updated Documentation

For details on scoping, visit our Scoping a Rule guide. For the endpoints, visit our API Reference for Create a rule, Update a rule, Update rule entities, and List rules. For the ASA request payload, visit our Auth Stream Access Request reference.

If you have any questions or concerns, please contact us via the HELP link in your Lithic Dashboard.

The Lithic changelog has an RSS feed! To monitor for new update announcements, subscribe with your preferred RSS reader.