Authentication

Authenticate user

Obtain an access token to authenticate a user and start a new session.

The Authenticate User endpoint verifies a user’s credentials and issues new access and refresh tokens. Use this endpoint when a user logs in with their username/email and password.

Endpoint

POST /v1/auth/login

Headers

Key	Value	Required
Content-Type	application/json	Yes

Request Body

{
  "email": "user@example.com",
  "password": "your_password_here"
}

Field	Type	Description
email	string	The user’s email address or username.
password	string	The user’s password (plaintext).

Response

Successful Response (200 OK)

{
  "access_token": "access_token_value",
  "refresh_token": "refresh_token_value",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "Jane Doe"
  }
}

Field	Type	Description
access_token	string	Token to be used in API requests.
refresh_token	string	Token to obtain new access tokens when expired.
token_type	string	Always Bearer.
expires_in	int	Token lifetime in seconds.
user	object	Basic user profile information.

Error Response (401 / 400)

{
  "error": "invalid_credentials",
  "message": "Email or password is incorrect."
}

Error Code	Meaning
invalid_credentials	Incorrect email or password.
unauthorized	Authentication failed.
invalid_request	Missing or malformed fields.

Example Usage

cURL

curl -X POST "https://api.example.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password_here"
  }'

JavaScript (Fetch)

const response = await fetch("https://api.example.com/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "user@example.com",
    password: "your_password_here"
  })
});

const data = await response.json();
console.log(data.access_token);

For best security practices, always transmit login requests over HTTPS, and never log user passwords.

Invalidate session

Retrieve a user

Need help? Contact Support

Join our Discord Community

Questions? Contact Sales

On this page

Title