Authorization Controls
An authorization control limits spending by specified users at specified merchants. You can limit spending at a single merchant or at a group of merchants, and you can limit spending by a single user, users with a particular card product, or all users.
You can block spending at all merchants by default and then allow it for specific merchants, or you can allow spending at all merchants by default and block it at specific merchants.
Tip
See Controlling Spending for a tutorial that walks you through the creation of a spend control.
Create authorization control
Copy section link
Action: POST
Endpoint: /authcontrols
Limit where a user can make transactions to a single merchant or group of merchants. If multiple authorization controls apply to the same user, the limits of all controls are combined.
Note
You can create program-level controls in your user sandbox. However, you must work with your Marqeta representative to create program-level controls in a production environment.
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the authorization control. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 36 char max |
name
string
|
The name of the authorization control. Allowable Values: 255 char max |
active
boolean
|
Indicates whether the authorization control is active.
If the control will be used for Commando Mode, set to Allowable Values:
Default value: |
start_time
string
|
The date and time when the exception goes into effect. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
end_time
string
|
The date and time when the exception ends. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
merchant_scope
object
|
Defines the group of merchants to which the authorization control applies.
This object is required if the If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all merchants. Allowable Values: A valid |
association
object
|
Defines the group of users to which the authorization control applies.
This object is required if the If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the authorization control applies to all users. Allowable Values: A valid |
The merchant_scope object
Copy section link
| Fields | Description |
|---|---|
mid
string
|
MID (Merchant ID). The unique identification number of a merchant. Enter a value to control access to a particular merchant. Allowable Values: 36 char max |
mcc
string
|
A single MCC (Merchant Category Code). Identifies the type of goods or services provided by the merchant. Enter a value to control access to a particular type of product or service. Allowable Values: 4 char max |
mcc_group
string
|
Token identifying a group of MCCs. Enter a value to control access to a group of product or service types. Allowable Values: Existing MCC group token. Send a |
The association object
Copy section link
| Fields | Description |
|---|---|
card_product_token OR user_token
string
|
Token identifying either a card product or user. Specify a card product token in the Pass either Allowable Values: Existing card product or user token. Send a |
Retrieve authorization control
Copy section link
Action: GET
Endpoint: /authcontrols/{token}
Retrieve a specific authorization control.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Identifies the authorization control to return. Allowable Values: Existing authorization control token. Send a |
Update authorization control
Copy section link
Action: PUT
Endpoint: /authcontrols/{token}
Update a specific authorization control.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Identifies the authorization control to update. Allowable Values: Existing authorization control token. Send a |
Body field details
Copy section link
| Fields | Description |
|---|---|
name
string
|
The name of the authorization control. Allowable Values: 255 char max |
active
boolean
|
Indicates whether the authorization control is active. Allowable Values:
Default value: |
start_time
string
|
The date and time when the exception goes into effect. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
end_time
string
|
The date and time when the exception ends. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
merchant_scope
object
|
Defines the group of merchants to which the exception applies. You must populate one or more fields of this object. If no fields are populated, the exception applies to all merchants. Allowable Values: A valid |
association
object
|
Defines a card product or user to which the authorization control applies.
NoteIf this object is included in the authorization control that you are updating, then you must include this object in your request even if you do not intend to update its values. If you do not include this object when you update your authorization control, its existing values will be overwritten and can cause unexpected behavior.Allowable Values: A valid |
The merchant_scope object
Copy section link
| Fields | Description |
|---|---|
mid
string
|
Merchant identifier (MID). The unique identification number of a merchant. Enter a value to control access to a particular merchant. Allowable Values: 36 char max |
mcc
string
|
A single merchant category code (MCC). Identifies the type of goods or services provided by the merchant. Enter a value to control access to a particular type of product or service. Allowable Values: 4 char max |
mcc_group
string
|
Token identifying a group of MCCs. Enter a value to control access to a group of product or service types. Allowable Values: Existing MCC group token. Send a |
The association object
Copy section link
| Fields | Description |
|---|---|
card_product_token OR user_token
string
|
Token identifying either a card product or user. Specify a card product token in the Pass either Allowable Values: Existing card product or user token. Send a |
List authorization controls
Copy section link
Action: GET
Endpoint: /authcontrols
List all authorization controls associated with a specific user or card product, or list all authorization controls defined in your program.
Include either a user or a card_product query parameter to indicate the user or card product whose associated authorization controls you want to retrieve (do not include both).
To list all authorization controls for your program, omit the user and card_product query parameters from your request.
This endpoint supports field filtering and pagination.
Query parameters
Copy section link
| Fields | Description |
|---|---|
user
string
|
The token identifying the user whose associated authorization controls you want to retrieve. Enter the string "null" to list authorization controls that are not associated with a user. Allowable Values: Existing user token or the string "null". Send a |
card_product
string
|
The token identifying the card product whose associated authorization controls you want to retrieve. Enter the string "null" to list authorization controls that are not associated with a card product. Allowable Values: Existing card product token or the string "null". Send a |
Create a merchant (MID) exemption
Copy section link
Action: POST
Endpoint: /authcontrols/exemptmids
Exempt an individual merchant from authorization controls. Transactions originating from this MID ignore any otherwise applicable authorization controls.
Note
You can create MID exemptions in your user sandbox. However, you must work with your Marqeta representative to create MID exemptions in a production environment.
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the MID exemption. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 36 char max |
name
string
|
The name of the MID exemption. Allowable Values: 255 char max |
mid
string
|
The merchant to be exempted.
This field is required if there is no entry in the Allowable Values: Existing merchant identifier. |
merchant_group_token
string
|
The token of the merchant group to be exempted.
This field is required if there is no entry in the Allowable Values: A valid merchant group token. For information about merchant groups, see Merchant Groups. |
association
object
|
The card product or user to which the MID exemption applies. If you include this object in your request, you must populate one or more of its fields. If no fields are populated, the MID exemption applies to all users. Allowable Values: A valid |
The association object
Copy section link
| Fields | Description |
|---|---|
card_product_token OR user_token
string
|
Token identifying either a card product or user. Specify a card product token in the Pass either Allowable Values: Existing card product or user token. Send a |
Retrieve a merchant (MID) exemption
Copy section link
Action: GET
Endpoint: /authcontrols/exemptmids/{token}
Retrieve a merchant (MID) exemption.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The MID exemption to return. Allowable Values: Existing MID exemption token. Send a |
List merchant (MID) exemptions
Copy section link
Action: GET
Endpoint: /authcontrols/exemptmids
Retrieve a list of all merchant (MID) exemptions.
Query parameters
Copy section link
| Fields | Description |
|---|---|
user
string
|
The token identifying the user whose associated MID exemptions you want to retrieve. Enter the string "null" to list MID exemptions that are not associated with a user. Allowable Values: Existing user token or the string "null". Send a |
card_product
string
|
The token identifying the card product whose associated MID exemptions you want to retrieve. Enter the string "null" to list MID exemptions that are not associated with a card product. Allowable Values: Existing card product token or the string "null". Send a |