login

Overview

Authenticates a user with email and password and returns a Sanctum personal access token. The token is sent on every subsequent call in the Authorization: Bearer {token} header.

The endpoint is stateless by design: it does not call Auth::attempt() and never starts a session. Credentials are checked directly against the user provider of the api guard.

Controller: App\Http\Controllers\Api\V1\Auth\AuthController::login()
Route name: api.v1.auth.login

Authentication

Type: None. Public endpoint.
Additional middleware: throttle:auth — 10 requests per minute per IP address.

Request

Method: POST
Path: /api/v1/auth/login
Content-Type: application/json

Body

{
  "email": "diver@example.com",
  "password": "SecurePass123!",
  "device_name": "Alex's iPhone"
}

Field	Type	Required	Validation	Description
`email`	`string`	Yes	`required\|email:rfc`	Registered email address
`password`	`string`	Yes	`required\|string`	Account password
`device_name`	`string`	No	`sometimes\|string\|max:255`	Label for this token, shown to the user on their devices screen

Validated by App\Http\Requests\Api\V1\Auth\LoginRequest.

When device_name is omitted or blank, the server derives a label from the User-Agent header as {platform} - {browser}, falling back to Unknown for either part, and to Mobile device when neither can be determined. Supplying a meaningful device_name is strongly recommended: it is what the account holder sees when deciding which device to revoke.

Example request

Response `200 OK`

{
  "success": true,
  "status": "success",
  "message": "OK",
  "data": {
    "token": "20|raid_ydVCW8OH9aAkZIKDuWAIOmNA6BFdfZrbAPZtpzFjebcf",
    "token_type": "Bearer",
    "expires_in": 7775999
  }
}

Response fields

Field	Type	Nullable	Always present	Description
`data.token`	`string`	No	Yes	Opaque personal access token. Send it verbatim as `Authorization: Bearer {token}`
`data.token_type`	`string`	No	Yes	Always `Bearer`
`data.expires_in`	`integer`	No	Yes	Seconds until expiry. 90 days, so approximately `7776000`. Treat it as approximate: it is computed at response time and truncates to the second

Errors

`401 Unauthorized` — wrong credentials

{
  "success": false,
  "status": "error",
  "message": "Invalid credentials"
}

The same message is returned for an unknown email and for a wrong password, deliberately: the endpoint does not reveal whether an address is registered.

`422 Unprocessable Entity` — validation

{
  "success": false,
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "email": ["The email field must be a valid email address."],
    "password": ["The password field is required."]
  }
}

`429 Too Many Requests`

Returned by the auth rate limiter after 10 requests in one minute from the same IP address, counting successful and failed attempts alike.

Notes

Tokens are Sanctum personal access tokens, not JWTs. They are opaque strings of the form {id}|raid_{random}, carry no readable payload, and are stored server-side, which is what makes individual revocation possible.

Tokens live 90 days and do not rotate. There is no refresh endpoint: when a token expires the user logs in again.

Every login issues a new independent token. Logging in from a second device does not invalidate the first.

Tokens are issued with the * ability.

A password reset revokes every token on the account. A password change from the profile endpoint revokes every token except the one making the request.

The account holder can see and revoke individual tokens from their privacy screen in the web application.

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

application/json

Bodyapplication/json

Example

{
    "status": "success",
    "message": "string",
    "data": {
        "token": "string",
        "token_type": "Bearer",
        "expires_in": 0
    }
}

Login and get Sanctum token

POST /api/v1/auth/login

Overview

Authentication

Request

Body

Example request

Response `200 OK`

Response fields

Errors

`401 Unauthorized` — wrong credentials

`422 Unprocessable Entity` — validation

`429 Too Many Requests`

Notes

Request

Request Code Samples

Responses

Login and get Sanctum token

POST /api/v1/auth/login#

Overview#

Authentication#

Request#

Body#

Example request#

Response 200 OK#

Response fields#

Errors#

401 Unauthorized — wrong credentials#

422 Unprocessable Entity — validation#

429 Too Many Requests#

Notes#

Request

Request Code Samples

Responses

POST /api/v1/auth/login

Overview

Authentication

Request

Body

Example request

Response `200 OK`

Response fields

Errors

`401 Unauthorized` — wrong credentials

`422 Unprocessable Entity` — validation

`429 Too Many Requests`

Notes