Authentication
Marqeta’s Core API enforces HTTP Basic Authentication on incoming requests.
This mechanism utilizes the standard Authorization field in the header for holding the credentials.
Authentication types
Copy section link
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, an admin 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 and Authorization Level | Application Token Required as Username | Admin Access Token Required as Password | User Access Token Required as Password | Single-Use Access Token Required as Password |
|---|---|---|---|---|
Unauthenticated Authorizes access to public API endpoints and data. |
✓ |
|||
Admin Authorizes access to all API endpoints and data associated with the program. |
✓ |
✓ |
||
User Authorizes access to all API endpoints and data associated with the user. |
✓ |
✓ |
||
User single-use Authorizes a single request with access to all API endpoints and data associated with the user. |
✓ |
✓ |
||
Client access Displays a virtual card’s sensitive data. |
✓ |
✓ |
Obtaining tokens
Copy section link
Marqeta distributes application tokens and admin 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 the Core API:
-
A
POSTrequest to the/users/auth/loginendpoint returns a user access token that is valid until the user is logged out or times out. -
A
POSTrequest to the/users/auth/onetimeendpoint returns a single-use access token for a specified user that is valid for a single request. -
A
POSTrequest to the/users/auth/clientaccesstokenendpoint returns an access token for a specified card that is valid for a single request.
See the Log in user, Create single-use token, and Create client access token sections of the Users API reference page for more information about these endpoints.
Expiration and throttling
Copy section link
Application tokens and admin access tokens never expire. User access tokens and user single-access tokens expire after 120 minutes. Client access token expire after 5 minutes.
Requesting a user access, user single-access, or a client access token using incorrect credentials returns an HTTP 401 status code. A throttling mechanism limits token requests to three within any 60 consecutive seconds. Throttled token requests also return an HTTP 401 status code.
cURL example
Copy section link
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.