All requests must provide the application token as the username. This token identifies the application that sent the request. The password can be either unspecified, a master access token, a user access token, or a single-use access token. Depending on the password value provided, the Marqeta platform assigns one of four authentication types to the request. Each authentication type corresponds to an authorization level that controls the request's access to API endpoints and data.
The following table summarizes the Marqeta platform authentication types and their corresponding authorization levels.
|Authentication Type||Application Token Required as Username||Master Access Token Required as Password||User Access Token Required as Password||Single-Use Access Token Required as Password||Authorization Level|
|Unauthenticated||X||Authorizes access to public API endpoints and data.|
|Master||X||X||Authorizes access to all API endpoints and data associated with the program.|
|User||X||X||Authorizes access to all API endpoints and data associated with the user.|
|User single-use||X||X||Authorizes a single request with access to all API endpoints and data associated with the user.|
Marqeta distributes application tokens and master access tokens directly to customers. These tokens are static, meaning that you can reuse them indefinitely.
User access tokens and single-use access tokens are dynamically allocated by way of the Core API. A POST request to the /users/auth/login endpoint returns a user access token that is valid until the user is logged out or times out. A POST request to the /users/auth/onetime endpoint returns a single-use access token for a specified user that is valid for a single request. See the "Log in User" and "Return Single-Use Token" sections of the Users page for more information about these endpoints.
Expiration and throttling
Application tokens and master access tokens never expire. User access tokens and user single-access tokens expire after 120 minutes.
Requesting a user access or user single-access token using incorrect credentials returns an HTTP 401 status code. A throttling mechanism limits token requests to 3 within any 60 consecutive seconds. Throttled token requests also return an HTTP 401 status code.
This example illustrates a call (in cURL format) to retrieve account balances for a user. The user's ID token is "bigbird_token". The user's current user access token is "user_access_token". The application token is "application_token".
curl -X GET --user application_token:user_access_token -H "Content-Type: application/json" "https://shared-sandbox-api.marqeta.com/v3/users/bigbird_token/balances"