DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

15 minute read

April 3, 2020

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Optional

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
Required

The name of the authorization control.

Allowable Values:

255 char max

active

boolean
Optional

Indicates whether the authorization control is active.

Allowable Values:

true, false

Default value: true

start_time

string
Optional

The date and time the exception goes into effect.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

end_time

string
Optional

The date and time the exception ends.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

merchant_scope

object
Required, if `association` is empty

Defines the group of merchants to which the authorization control applies.

You must populate one or more fields of this object. If no fields are populated, the authorization control applies to all merchants.

Allowable Values:

association

object
Required, if `merchant_scope` is empty

Defines the group of users to which the authorization control applies.

You must populate one or more fields of this object. If no fields are populated, the authorization control applies to all users.

Allowable Values:

The merchant_scope object
Copy section link

Fields Description

mid

string
Optional

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
Optional

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
Optional

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 GET request to /mccgroups to retrieve MCC group tokens.

The association object
Copy section link

Fields Description

card_product_token OR user_token

string
Required

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.

Allowable Values:

Existing card product or user token.

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

Sample request body
Copy section link

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

Is this helpful?

Sample response body
Copy section link

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

Is this helpful?

Retrieve authorization control
Copy section link

Action: GET
Endpoint: /authcontrols/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve a specific authorization control.

URL path parameters
Copy section link

Fields Description

token

string
Required

Identifies the authorization control to return.

Allowable Values:

Existing authorization control token.

Send a GET request to /authcontrols to retrieve authorization control tokens.

Sample response body
Copy section link

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

Is this helpful?

Update authorization control
Copy section link

Action: PUT
Endpoint: /authcontrols/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Update a specific authorization control.

URL path parameters
Copy section link

Fields Description

token

string
Required

Identifies the authorization control to update.

Allowable Values:

Existing authorization control token.

Send a GET request to /authcontrols to retrieve authorization control tokens.

Body field details
Copy section link

Fields Description

name

string
Required

The name of the authorization control.

Allowable Values:

255 char max

active

boolean
Optional

Indicates whether the authorization control is active.

Allowable Values:

true, false

Default value: true

start_time

string
Optional

The date and time the exception goes into effect.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

end_time

string
Optional

The date and time the exception ends.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

merchant_scope

object
Optional

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:

association

object
Required

Defines the group of users to which the authorization control applies.

You must populate one or more fields of this object. If no fields are populated, the authorization control applies to all users.

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

Allowable Values:

The merchant_scope object
Copy section link

Fields Description

mid

string
Optional

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
Optional

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
Optional

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 GET request to /mccgroups to retrieve MCC group tokens.

The association object
Copy section link

Fields Description

card_product_token

OR

user_token

string
Required

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.

Allowable Values:

Existing card product or user token.

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

Sample request body
Copy section link

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

Is this helpful?

Sample response body
Copy section link

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

Is this helpful?

List authorization controls
Copy section link

Action: GET
Endpoint: /authcontrols

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Optional

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 GET request to /users to retrieve existing tokens.

card_product

string
Optional

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 GET request to /cardproducts to retrieve existing tokens.

Sample response body
Copy section link

{
  "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"
      }
    }
  ]
}

Is this helpful?

Create a merchant (MID) exemption
Copy section link

Action: POST
Endpoint: /authcontrols/exemptmids

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Optional

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
Required

The name of the MID exemption.

Allowable Values:

255 char max

mid

string
Required

The merchant to be exempted.

Allowable Values:

association

object
Optional

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.

Allowable Values:

The association object
Copy section link

Fields Description

card_product_token OR user_token

string
Required

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.

Allowable Values:

Existing card product or user token.

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

Sample request body
Copy section link

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

Is this helpful?

Sample response body
Copy section link

{
  "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"
}

Is this helpful?

Retrieve a merchant (MID) exemption
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve a merchant (MID) exemption.

URL path parameters
Copy section link

Fields Description

token

string
Required

The MID exemption to return.

Allowable Values:

Existing MID exemption token.

Send a GET request to /authcontrols/exemptmids to retrieve MID exemption tokens.

Sample response body
Copy section link

{
  "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"
}

Is this helpful?

List merchant (MID) exemptions
Copy section link

Action: GET
Endpoint: /authcontrols/exemptmids

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve a list of all merchant (MID) exemptions.

Query parameters
Copy section link

Fields Description

user

string
Optional

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 GET request to /users to retrieve existing tokens.

card_product

string
Optional

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 GET request to /cardproducts to retrieve existing tokens.

Sample response body
Copy section link

{
  "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"
    }
  ]
}

Is this helpful?

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.