Guides
StatusDashboard

Authorization Rule Lifecycle

Draft, test in shadow mode, promote, disable, and delete Authorization Rules, plus list, fetch, and version history.

Overview

Every Authorization Rule follows the same lifecycle: you draft a rule, which runs in shadow mode so you can observe its impact without affecting live transactions; you promote the draft to make it active; and you disable or delete it when it is no longer needed. This page covers creating, retrieving, and managing rules through that lifecycle.

The same lifecycle applies to every rule type and event stream, including Conditional Action Rules, Velocity Limit Rules, Tokenization Rules, 3DS Authentication Rules, and Custom Code Rules.

Rule States

A rule has a top-level state that is either ACTIVE or INACTIVE. Draft status is conveyed separately by the draft_version object on the rule, not by the rule's state:

  • Rule state: ACTIVE (affecting live transactions) or INACTIVE (not affecting transactions)
  • draft_version.state: PENDING (the draft is compiling; applies to Custom Code Rules), SHADOWING (the draft is evaluating in shadow mode alongside the current active version), or ERROR (the draft failed to compile)
  • Version state (from version history): ACTIVE (the live version), SHADOW (a version that ran in shadow mode), or INACTIVE (a superseded or disabled version)

Drafting a New Rule

To draft a new rule, use the POST /v2/auth_rules endpoint. Specify the rule type, event stream, parameters, and the entities the rule applies to. The rule is created with no active version and a draft_version that runs in shadow mode.

For most rule types the draft begins running in shadow mode immediately. For Custom Code Rules (TYPESCRIPT_CODE), the code compiles asynchronously first: the draft_version.state is PENDING during compilation, then transitions to SHADOWING once it succeeds, or ERROR if compilation fails.

Scoping a Rule

Rules can be scoped to one of three entity levels:

  • Program level: set program_level: true to apply the rule across the entire card program. Optionally use excluded_card_tokens, excluded_account_tokens, or excluded_business_account_tokens to exempt specific cards or accounts
  • Account level: provide account_tokens and/or business_account_tokens to apply the rule to specific accounts
  • Card level: provide card_tokens to apply the rule to specific cards

Example Request

{
  "name": "Block gambling MCCs",
  "program_level": true,
  "type": "CONDITIONAL_ACTION",
  "event_stream": "AUTHORIZATION",
  "parameters": {
    "action": "DECLINE",
    "conditions": [
      {
        "attribute": "MCC",
        "operation": "IS_ONE_OF",
        "value": ["7801", "7802", "7995"]
      }
    ]
  }
}

Once the rule is created, it runs in shadow mode. To learn how shadow mode works and how to measure a draft rule's impact before promoting it, see Analytics and Observability.

Promoting a Rule

When you are confident in a draft rule, promote it with the POST /v2/auth_rules/{auth_rule_token}/promote endpoint. The request takes no body parameters.

Promotion makes the draft the new active version, replacing any existing active version, and the draft_version returns to null. Once promoted, the rule begins affecting authorizations in real time.

The previously active version is set to inactive but is not destroyed. It remains visible in the rule's version history. There is no endpoint to re-activate a prior version directly; to restore an earlier configuration, create a new draft with those parameters and promote it.

Disabling a Rule

To disable a rule, use the PATCH /v2/auth_rules/{auth_rule_token} endpoint and set the rule's state to INACTIVE. The rule stops affecting authorizations.

{
  "state": "INACTIVE"
}
🚧

Disabling a rule clears the rule's current_version from the response. Any existing draft_version is retained. The PATCH endpoint cannot re-activate a rule (its state can only be set to INACTIVE); to make a rule active again, promote a draft.

The previously active configuration is preserved in version history, even though the current_version parameter is cleared from the rule response.

Clearing a Draft

To clear a draft without affecting the active rule, call the POST /v2/auth_rules/{auth_rule_token}/draft endpoint with parameters set to null:

{
  "parameters": null
}

This stops the draft from running in shadow mode. The active version, if any, is unchanged.

Deleting a Rule

To permanently remove a rule, use the DELETE /v2/auth_rules/{auth_rule_token} endpoint. A successful deletion returns a 204 No Content response. Unlike disabling, deletion cannot be undone and the rule is no longer retrievable. If you may need the rule again, disable it instead of deleting it.

Retrieving Rules

Listing Rules

Use the GET /v2/auth_rules endpoint to list all rules under your program. Filter the response with:

  • account_token / card_token / business_account_token: rules associated with a specific entity
  • scope: filter by rule scope (PROGRAM, ACCOUNT, BUSINESS_ACCOUNT, CARD, or ANY)
  • event_streams: one or more event streams (for example, AUTHORIZATION, TOKENIZATION, THREE_DS_AUTHENTICATION, ACH_DEBIT_RECEIPT, ACH_CREDIT_RECEIPT). The singular event_stream parameter still works but is deprecated in favor of event_streams
  • page_size: results per page (1–100, default 50)

Fetching a Rule by Token

Use the GET /v2/auth_rules/{auth_rule_token} endpoint to retrieve a single rule, including its state, current_version, and any draft_version.

Viewing Version History

Use the GET /v2/auth_rules/{auth_rule_token}/versions endpoint to retrieve every version of a rule, newest first. Each version includes its parameters and its state (ACTIVE, SHADOW, or INACTIVE). This is how previously active configurations remain available after a promotion or a disable.

Lithic-Managed Rules

Some rules in your program may be flagged as lithic_managed. These rules are managed by Lithic and cannot be modified or deleted through the API or Dashboard. They appear in rule listings and in rule results but are not editable.

Next Steps

Updated 1 day ago