> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Log in user

> To log in a user and return a user access token, send a POST request to the /users/auth/login endpoint and include the user details in JSON format in the body of the request.

POST/users/auth/login

To log in a user and return a user access token, send a `POST` request to the `/users/auth/login` endpoint and include the user details in [JSON](http://www.json.org/) format in the body of the request.

> [!TIP]
>
> **Tip**\
> To check a user's credentials without logging out the user, call the `/users/auth/onetime` endpoint.

## Request body

| Fields | Description |
| - | - |
| email string  Optional | Cardholder email address. **Allowable Values:**  255 char max |
| password string  Optional | Password to the cardholder's user account on the Marqeta platform. **Allowable Values:**  1–255 chars |
| user\_token string  Optional | Identifies the cardholder to log in. Send a `GET` request to `/users` to retrieve user tokens. **Allowable Values:**  1–36 chars |

## Sample request body

```json JSON lines wrap theme={null}
{
  "email": "jane.doe@company.com",
  "password": "P@ssw0rd",
  "user_token": "my_user_01"
}
```

## Response body

| Fields | Description |
| - | - |
| access\_token object  Conditionally returned | Contains a cardholder's login access information. **Allowable Values:**  Existing `access_token` |
| access\_token.**application** object  Conditionally returned | Contains client application information. **Allowable Values:**  Existing `application` object |
| access\_token.application.**access\_code** string  Conditionally returned | Access code of the client application. **Allowable Values:**  255 char max |
| access\_token.application.**assets\_url** string  Conditionally returned | URL of the client application assets. **Allowable Values:**  255 char max |
| access\_token.application.**client\_api\_base\_url** string  Conditionally returned | Base URL of the client API. **Allowable Values:**  255 char max |
| access\_token.application.**environment** string  Conditionally returned | Client application's environment. **Allowable Values:**  255 char max |
| access\_token.application.**program** string  Conditionally returned | Name of the program on the Marqeta platform. **Allowable Values:**  255 char max |
| access\_token.application.**program\_short\_code** string  Conditionally returned | Short code of the program on the Marqeta platform. **Allowable Values:**  255 char max |
| access\_token.application.**token** string  Conditionally returned | Unique identifier of the `application` object. **Allowable Values:**  36 char max |
| access\_token.**expires** datetime  Returned | Date and time when the access token expires. **Allowable Values:**  datetime **Format:** yyyy-MM-ddThh:mm:ssZ |
| access\_token.**master\_roles** array of strings  Conditionally returned | Array of master roles. **Allowable Values:**  Valid array of one or more `master_roles` strings |
| access\_token.**one\_time** boolean  Conditionally returned | Indicates whether the access token is a single-use token. **Allowable Values:**  `true`, `false` |
| access\_token.**token** string  Conditionally returned | Unique identifier of the access token. **Allowable Values:**  36 char max |
| access\_token.**token\_type** string  Conditionally returned | Specifies the type of access token. **Allowable Values:**  `single_use`, `user`, `admin` |
| access\_token.**user\_token** string  Conditionally returned | Unique identifier of the user resource. **Allowable Values:**  36 char max |
| user object  Conditionally returned | Contains information about a cardholder. **Allowable Values:**  `account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip` |
| user.**account\_holder\_group\_token** string  Conditionally returned | Associates the specified account holder group with the cardholder. **Allowable Values:**  36 char max |
| user.**active** boolean  Conditionally returned | Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. **Allowable Values:**  `true`, `false` |
| user.**address1** string  Conditionally returned | Cardholder's address. **Allowable Values:**  255 char max |
| user.**address2** string  Conditionally returned | Additional address information for the cardholder. **Allowable Values:**  255 char max |
| user.**authentication** object  Conditionally returned | Contains the cardholder's email address and password information. **Allowable Values:**  `email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time` |
| user.authentication.**email\_verified** boolean  Conditionally returned | Specifies whether the email address has been verified. **Allowable Values:**  `true`, `false` |
| user.authentication.**email\_verified\_time** datetime  Conditionally returned | Date and time when the email address was verified. **Allowable Values:**  datetime **Format:** yyyy-MM-ddThh:mm:ssZ |
| user.authentication.**last\_password\_update\_channel** string  Conditionally returned | Specifies the channel through which the password was last changed. **Allowable Values:**  `USER_CHANGE`, `USER_RESET` |
| user.authentication.**last\_password\_update\_time** datetime  Conditionally returned | Date and time when the password was last changed. **Allowable Values:**  datetime **Format:** yyyy-MM-ddThh:mm:ssZ |
| user.**birth\_date** string  Conditionally returned | Cardholder's date of birth. **Allowable Values:**  Format: yyyy-MM-dd |
| user.**birth\_place** string  Conditionally returned | Country where the cardholder was born. **Allowable Values:**  255 char max  ISO 3166 two-character country codes. For example, the country code for the United States is `US`.  The ISO maintains the [full list of ISO-3166 country codes](https://www.iso.org/iso-3166-country-codes.html). |
| user.**business\_token** string  Conditionally returned | Unique identifier of the business resource. **Allowable Values:**  Existing business resource token |
| user.**city** string  Conditionally returned | City where the cardholder resides. **Allowable Values:**  40 char max |
| user.**company** string  Conditionally returned | Company name. **Allowable Values:**  255 char max |
| user.**corporate\_card\_holder** boolean  Conditionally returned | Specifies if the cardholder holds a corporate card. **Allowable Values:**  `true`, `false` |
| user.**country** string  Conditionally returned | Country where the cardholder resides. **Allowable Values:**  40 char max |
| user.**created\_time** datetime  Returned | Date and time when the resource was created, in UTC. **Allowable Values:**  datetime **Format:** yyyy-MM-ddThh:mm:ssZ |
| user.**email** string  Conditionally returned | Valid email address of the cardholder. **Allowable Values:**  1–255 chars |
| user.**first\_name** string  Conditionally returned | Cardholder's first name. **Allowable Values:**  40 char max |
| user.**gender** string  Conditionally returned | Gender of the cardholder. **Allowable Values:**  `F`, `M` |
| user.**honorific** string  Conditionally returned | Cardholder's title or prefix: Dr., Miss, Mr., Ms., and so on. **Allowable Values:**  10 char max |
| user.**id\_card\_expiration\_date** string  Conditionally returned | Expiration date of the cardholder's identification. **Allowable Values:**  Format: yyyy-MM-dd |
| user.**id\_card\_number** string  Conditionally returned | Cardholder's identification card number. **Allowable Values:**  255 char max |
| user.**identifications** array of objects  Conditionally returned | One or more objects containing identifications associated with the cardholder. **Allowable Values:**  Valid array of one or more `identifications` objects |
| user.identifications\[].**expiration\_date** string  Conditionally returned | Expiration date of the identification, if applicable. **Allowable Values:**  Format: yyyy-MM-dd |
| user.identifications\[].**type** string  Conditionally returned | Type of identification. **Allowable Values:**  `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE` |
| user.identifications\[].**value** string  Conditionally returned | Number associated with the identification. **Allowable Values:**  255 char max |
| user.**ip\_address** string  Conditionally returned | Cardholder's IP address. **Allowable Values:**  39 char max |
| user.**last\_modified\_time** datetime  Returned | Date and time when the resource was last updated, in UTC. **Allowable Values:**  datetime **Format:** yyyy-MM-ddThh:mm:ssZ |
| user.**last\_name** string  Conditionally returned | Cardholder's last name. **Allowable Values:**  40 char max |
| user.**metadata** object  Conditionally returned | Associates any additional metadata you provide with the cardholder. **Allowable Values:**  You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| user.**middle\_name** string  Conditionally returned | Cardholder's middle name. **Allowable Values:**  40 char max |
| user.**nationality** string  Conditionally returned | Cardholder's nationality. **Allowable Values:**  255 char max |
| user.**notes** string  Conditionally returned | Any additional information pertaining to the cardholder. **Allowable Values:**  255 char max |
| user.**parent\_token** string  Conditionally returned | Unique identifier of the parent user or business resource. **Allowable Values:**  1–36 chars |
| user.**passport\_expiration\_date** string  Conditionally returned | Expiration date of the cardholder's passport. **Allowable Values:**  Format: yyyy-MM-dd |
| user.**passport\_number** string  Conditionally returned | Cardholder's passport number. **Allowable Values:**  40 char max |
| user.**password** string  Conditionally returned | Password to the cardholder's user account on the Marqeta platform. **Allowable Values:**  1–255 chars |
| user.**phone** string  Conditionally returned | Cardholder's telephone number. **Allowable Values:**  255 char max |
| user.**postal\_code** string  Conditionally returned | Postal code of the cardholder's address. **Allowable Values:**  10 char max |
| user.**ssn** string  Conditionally returned | Cardholder's Social Security Number (SSN). **Allowable Values:**  Nine digits only, no delimiters. |
| user.**state** string  Conditionally returned | State or province where the cardholder resides. **Allowable Values:**  2 char max |
| user.**status** string  Conditionally returned | Specifies the status of the cardholder on the Marqeta platform. **Allowable Values:**  `UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED` |
| user.**title** string  Conditionally returned | Professional title of the cardholder, such as Chief Comptroller. **Allowable Values:**  255 char max |
| user.**token** string  Conditionally returned | Unique identifier of the cardholder. **Allowable Values:**  1–36 chars |
| user.**uses\_parent\_account** boolean  Conditionally returned | Indicates whether the child shares balances with the parent (`true`), or the child's balances are independent of the parent (`false`). **Allowable Values:**  `true`, `false` |
| user.**zip** string  Conditionally returned | United States ZIP code of the cardholder's address. **Allowable Values:**  10 char max |

## Sample response body

```json JSON lines wrap theme={null}
{
  "access_token": {
    "token": "e12b1f64-1444-4aa3-83d9-347800c68e94",
    "expires": "2027-03-01T21:02:04Z",
    "one_time": false
  },
  "user": {
    "token": "my_user_01",
    "active": true,
    "email": "jane.doe@company.com",
    "uses_parent_account": false,
    "password": "P@ssw0rd",
    "created_time": "2023-04-01T17:52:39Z",
    "last_modified_time": "2023-04-01T17:52:39Z"
  }
}
```


## Related topics

- [Users Overview](https://www.marqeta.com/docs/core-api/users.md)
- [User Authentication Overview](https://www.marqeta.com/docs/core-api/users/user-authentication.md)
- [Authentication](https://www.marqeta.com/docs/core-api/authentication.md)
- [Log out user](https://www.marqeta.com/docs/core-api/users/user-authentication/logout.md)
- [Managing User Profiles in the Marqeta Dashboard](https://www.marqeta.com/docs/developer-guides/user-profiles-dashboard.md)