### Authorization Rules (V1) Discontinued

Auth Rules (V1) has been superseded by a newer, improved version and V1 endpoints have been removed. The methods described on this page are no longer available. Please see [Auth Rules (V2)](https://docs.lithic.com/docs/authorization-rules-v2) for current information about improved Lithic-hosted Authorization Rules.

An authorization rule (Auth Rule) is a control you can set to better manage the transactions on your cards. It enables you to allow or block transactions in specific countries, and allow or block transactions at specific merchant types.

To minimize conflict, any given entity (program, account, card) that makes up your program can only have one Auth Rule directly applied to it. However, any higher-level entity's Auth Rule will apply to all entities below it - e.g., a given card's transactions will be subject to the Auth Rule applied to the account that the card belongs to AND the Auth Rule applied to the program that the card belongs to.

See [Merchant Category Codes (MCCs)](https://docs.lithic.com/docs/merchant-category-codes-mccs) for a detailed list of MCCs that can be used in creating and modifying Auth Rules.

# Auth Rule Schema

JSON

```json
{
  "token": String,
  "allowed_countries": List,
  "blocked_countries": List,
  "allowed_mcc": List,
  "blocked_mcc": List,
  "state": String,
  "program_level": Boolean,
  "card_tokens": List,
  "account_tokens": List
}
```

| Field                   | Description |
| ----------------------- | ----------- |
| token                   | Globally unique identifier for the Auth Rule |
| allowed_countries       | Countries in which the Auth Rule will permit transactions, listed in uppercase ISO 3166-1 alpha-3 three character abbreviations. |
| blocked_countries       | Countries in which the Auth Rule will decline transactions, listed in uppercase ISO 3166-1 alpha-3 three character abbreviations |
| allowed_mcc            | Merchant category codes for which the Auth Rule will permit transactions, listed in ISO 18245 four-digits. |
| blocked_mcc            | Merchant category codes for which the Auth Rule will decline transactions, listed in ISO 18245 four-digits |
| state                   | Indicates whether the Auth Rule is `ACTIVE` or `INACTIVE` |
| program_level           | Boolean indicating whether the Auth Rule will be applied at the program level |
| card_tokens             | Array of card_token(s) identifying the cards that the Auth Rule will apply to |
| account_tokens          | Array of account_token(s) identifying the accounts that the Auth Rule will apply to |

# Create Auth Rules

Creates an authorization rule and applies it at the program, account, or card level.

Request

```http
POST https://api.lithic.com/v1/auth_rules
```

#### Sample Request

cURL

```curl
curl https://api.lithic.com/v1/auth_rules \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
      "allowed_countries":["USA"],
      "allowed_mcc":["3000", "3001"],
      "program_level": true
}
'
```

#### Sample Response

JSON

```json
{
  "allowed_countries": ["USA"],
  "blocked_countries": [],
  "allowed_mcc": ["3000", "3001"],
  "blocked_mcc": [],
  "token": "d39e680e-af95-47ad-a78e-2415a0c8a81f",
  "program_level": true,
  "state": "ACTIVE",
  "card_tokens": [],
  "account_tokens": []
}
```

To successfully create an Auth Rule, at least one type of control parameter (country control, MCC control) and only one type of entity parameter (card, account, program-level) should be included in the request.

| Field                   | Description |
| ----------------------- | ----------- |
| allowed_countries _(optional)_ | List of countries in which the Auth Rule will permit transactions. |
| blocked_countries _(optional)_ | List of countries in which the Auth Rule will automatically decline transactions. |
| allowed_mcc _(optional)_ | List of merchant category codes for which the Auth Rule will permit transactions. |
| blocked_mcc _(optional)_ | List of merchant category codes for which the Auth Rule will automatically decline transactions. |
| card_tokens _(optional)_ | List of card_token(s) identifying the cards that the Auth Rule will apply to. |
| account_tokens _(optional)_ | List of account_token(s) identifying the accounts that the Auth Rule will apply to. |
| program_level _(optional)_ | Boolean indicating whether the Auth Rule should be applied at the program level. |

# Update Auth Rules

Update the properties associated with an existing authorization rule.

Request

```http
PUT https://api.lithic.com/v1/auth_rules/{auth_rule_token}
```

#### Sample Request

Bash

```shell
curl https://api.lithic.com/v1/auth_rules/d39e680e-af95-47ad-a78e-2415a0c8a81f \
  -X PUT \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
      "allowed_countries":["USA","CAN"],
      "blocked_mcc":["3000","3001"]
}
'
```

#### Sample Response

JSON

```json
{
  "allowed_countries": ["USA", "CAN"],
  "blocked_countries": [],
  "allowed_mcc": ["3000", "3001"],
  "blocked_mcc": [],
  "token": "d39e680e-af95-47ad-a78e-2415a0c8a81f",
  "program_level": true,
  "state": "ACTIVE",
  "card_tokens": [],
  "account_tokens": []
}
```

To update an Auth Rule, at least one type of control parameter (country control, MCC control) should be included in the request. Note that using this endpoint will update the entire configuration of the Auth Rule, not just the parameters passed in.

# List Auth Rules

List the properties and entities (program, accounts, and cards) associated with an existing authorization rule. If no Auth Rule token is provided, this endpoint will return all of the Auth Rules under the program.

Request

```http
GET https://api.lithic.com/v1/auth_rules/{auth_rule_token}
```

#### Sample Request

Bash

```shell
curl https://api.lithic.com/v1/auth_rules/d39e680e-af95-47ad-a78e-2415a0c8a81f \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

#### Sample Response

JSON

```json
{
  "allowed_countries": ["USA", "CAN"],
  "blocked_countries": [],
  "allowed_mcc": [],
  "blocked_mcc": ["3000", "3001"],
  "token": "d39e680e-af95-47ad-a78e-2415a0c8a81f",
  "program_level": true,
  "state": "ACTIVE",
  "card_tokens": [],
  "account_tokens": []
}
```

# Apply Auth Rule to Entity

Applies an existing authorization rule to a program, account(s), or card(s).

Request

```http
POST https://api.lithic.com/v1/auth_rules/{auth_rule_token}/apply
```

#### Sample Request

Bash

```shell
curl https://api.lithic.com/v1/auth_rules/d39e680e-af95-47ad-a78e-2415a0c8a81f/apply \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
      "account_tokens": ["ecbd1d58-0299-48b3-84da-6ed7f5bf9ec3"]
}
'
```

#### Sample Response

JSON

```json
{
  "allowed_countries": ["USA", "CAN"],
  "blocked_countries": [],
  "allowed_mcc": [],
  "blocked_mcc": ["3000", "3001"],
  "token": "d39e680e-af95-47ad-a78e-2415a0c8a81f",
  "program_level": true,
  "state": "ACTIVE",
  "card_tokens": [],
  "account_tokens": ["ecbd1d58-0299-48b3-84da-6ed7f5bf9ec3"]
}
```

# Remove Auth Rule from Entity

Remove an existing authorization rule from a program, account(s), or card(s). Note that any Auth Rule not applied to an entity will be automatically deactivated (i.e., status will be set to `INACTIVE`).

Request

```http
DELETE https://api.lithic.com/v1/auth_rules/remove
```

#### Sample Request

Bash

```shell
curl https://api.lithic.com/v1/auth_rules/remove/ \
  -X DELETE \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '
{
  "account_tokens":["ecbd1d58-0299-48b3-84da-6ed7f5bf9ec1"]
}
'
```

#### Sample Response

JSON

```json
{
  "account_tokens": ["ecbd1d58-0299-48b3-84da-6ed7f5bf9ec1"],
  "card_tokens": [],
  "program_level": false
}
```

# Auth Rules FAQ

**How do Auth Rules at various entity levels interact with each other?**  
When multiple Auth Rules apply to a given transaction, the most restrictive set of conditions will apply. For example, if an account-level Auth Rule allows transactions in the US and Canada, and a card-level Auth Rule allows for only the US, transactions on that card will be restricted to the US only.

**What are best practices to manage Auth Rules at scale?**  
We recommend applying Auth Rules at the highest-level entity possible. For example, if you know that all of your cards will only ever be used on a set of 3 MCCs, we recommend applying that Auth Rule to your program. This will make your Auth Rule easier to manage if you need to add a fourth MCC to the allowed list, as opposed to updating an Auth Rule and applying it to many individual cards.