Authorization Controls

An authorization control is a type of spend control that limits where users can transact. You can configure authorization controls to limit spending at a single merchant or a group of merchants. Authorization controls can apply to a single user, all users associated with a particular card product, or all users in your program.

Your program's default authorization behavior can block all merchants by default, enabling you to create an authorization control that adds one or more merchants to a whitelist, or it can allow all merchants by default, enabling you to create an authorization control that adds one or more merchants to a blacklist.

Note: See Controlling Spending for a tutorial that walks you through the creation of a spend control.

Create authorization control

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 the shared sandbox. However, you must work with your Marqeta Customer Success representative to create program-level controls in a production environment.

Body field details

Name Type Required? Description Allowable Values
token string No 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.
36 char max
name string Yes The name of the authorization control. 255 char max
active boolean No Indicates whether the authorization control is active. true | false

Default: true
start_time string No The date and time the exception goes into effect. yyyy-MM-ddThh:mm:ssZ
end_time string No The date and time the exception ends. yyyy-MM-ddThh:mm:ssZ
merchant_scope object No Defines the group of merchants to which the authorization control applies.

Populate no more than one field. If no fields are populated, the control applies to all merchants.
association object No Defines the group of users to which the authorization control applies.

Populate no more than one field. If no fields are populated, the control applies to all users.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control access to a particular merchant.
36 char max
mcc string No 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.
4 char max
mcc_group string No Token indentifying a group of MCCs.

Enter a value to control access to a group of product or service types.
Existing MCC group token.

Issue a GET to /mccgroups to retrieve MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the authorization control to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the authorization control to a single user.

Pass either card_product_token or user_token, not both.
Existing card product or user token.

Issue a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
"merchant_scope": {
"mid": "98765"
},
"association": {
"user_token": "bigbird_token"
},
"token": "my_authcontrol",
"name": "My Auth Control"
}

Sample response body

{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mid": "98765"
}
}


Retrieve authorization control

Action: GET
Endpoint: /authcontrols/{token}

Retrieve a specific authorization control.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the authorization control to return. Existing authorization control token.

Issue a GET to /authcontrols to retrieve authorization control tokens.

Sample response body

{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mid": "98765"
}
}


Update authorization control

Action: PUT
Endpoint: /authcontrols/{token}

Update a specific authorization control.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the authorization control to update. Existing authorization control token.

Issue a GET to /authcontrols to retrieve authorization control tokens.

Body field details

Name Type Required? Description Allowable Values
name string Yes The name of the authorization control. 255 char max
active boolean No Indicates whether the authorization control is active. true | false

Default: true
start_time string No The date and time the exception goes into effect. yyyy-MM-ddThh:mm:ssZ
end_time string No The date and time the exception ends. yyyy-MM-ddThh:mm:ssZ
merchant_scope object No Defines the group of merchants to which the exception applies.

Specify only one value. If no values are specified, the exception applies to all merchants.
association object Yes Defines the group of users to which the authorization control applies.

Populate no more than one field. If no fields are populated, the control applies to all users.

Note: You must include this object in your request even if you don't intend to update its values.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control access to a particular merchant.
36 char max
mcc string No 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.
4 char max
mcc_group string No Token indentifying a group of MCCs.

Enter a value to control access to a group of product or service types.
Existing MCC group token.

Issue a GET to /mccgroups to retreive MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the authorization control to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the authorization control to a single user.

Pass either card_product_token or user_token, not both.
Existing card product or user token.

Issue a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
"merchant_scope": {
"mcc": "5111"
}
}

Sample response body

{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mcc": "5111"
}
}


List authorization controls

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

Name Type Required? Description Allowable Values
user string No 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.
Existing user token or the string "null".

Issue a GET to /users to retrieve existing tokens.
card_product string No 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.
Existing card product token or the string "null".

Issue a GET to /cardproducts to retrieve existing tokens.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mcc": "5111"
}
}
]
}


Create MID exemption

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 the shared sandbox. However, you must work with your Marqeta Customer Success representative to create MID exemptions in a production environment.

Body field details

Name Type Required? Description Allowable Values
token string No 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.
36 char max
name string Yes The name of the MID exemption. 255 char max
mid string Yes The merchant to be exempted.
association object No The group of users to which the MID exemption applies.

Populate no more than one field. If no fields are populated, the MID exemption applies to all users.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the MID exemption to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the MID exemption to a single user.

Pass either card_product_token or user_token, not both.
Existing card product or user token.

Send a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
"token": "my_exempt_token",
"name": "my_exempt_mid",
"association": {
"card_product_token": "my_card_product"
},
"mid": "12345678901"
}

Sample response body

{
"token": "my_exempt_token",
"name": "my_exempt_mid",
"association": {
"card_product_token": "my_card_product"
},
"mid": "12345678901",
"active": true,
"created_time": "2018-06-19T13:22:07Z",
"last_modified_time": "2018-06-19T13:22:07Z"
}


Retrieve MID exemption

Action: GET
Endpoint: /authcontrols/exemptmids/{token}

Retrieve a specific MID exemption.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The MID exemption to return. Existing MID exemption token.

Issue a GET to /authcontrols/exemptmids to retrieve MID exemption tokens.

Sample response body

{
"token": "my_exempt_token",
"name": "my_exempt_mid",
"association": {
"card_product_token": "my_card_product"
},
"mid": "12345678901",
"active": true,
"created_time": "2018-06-19T13:22:07Z",
"last_modified_time": "2018-06-19T13:22:07Z"
}


List MID exemptions

Action: GET
Endpoint: /authcontrols/exemptmids

Retrieve a list of all MID exemptions.

Query parameters

Name Type Required? Description Allowable Values
user string No 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.
Existing user token or the string "null".

Issue a GET to /users to retrieve existing tokens.
card_product string No 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.
Existing card product token or the string "null".

Issue a GET to /cardproducts to retrieve existing tokens.

Sample response body


"count":2,
"start_index":0,
"end_index":1,
"is_more":false,
"data":[ 

"token":"my_exempt_authcontrol",
"name":"My Exempt Auth Control",
"active":true,
"mid": "984226812886",
"created_time":"2018-07-03T13:22:07Z",
"last_modified_time":"2018-07-03T17:22:07Z"
},

"token":"my_exempt_authcontrol_2",
"name":"My Exempt Auth Control 2",
"active":true,
"association": {                   
"card_product_token": "my_card_product", 
},
"mid": "1234567891",
"created_time":"2018-07-03T17:22:07Z",
"last_modified_time":"2018-07-03T17:22:07Z"
}
]
}