Skip to main content
POST
/
api
/
v1
/
auth
/
login
Login
curl --request POST \
  --url https://api.example.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "password": "<string>",
  "remember_me": true
}
'
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJlbWFpbCI6ImpvaG4uZG9lQGV4YW1wbGUuY29tIiwidXNlcm5hbWUiOiJqb2huX2RvZSIsImlzX3ZlcmlmaWVkIjp0cnVlLCJleHAiOjE3MDk3MzQ4NDV9.xyz...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJleHAiOjE3MTIyMzk2NDV9.abc...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "username": "john_doe",
    "is_verified": true,
    "is_active": true
  }
}

​
Endpoint

POST /api/v1/auth/login
Authenticates a user with email and password, returning JWT tokens for API access. Tracks failed login attempts and may lock accounts after multiple failures.

​
Request Body

​
email
string
required
User’s registered email address.Format: Valid email format (validated by EmailStr)Example: user@example.com
​
password
string
required
User’s password.Minimum: 1 characterExample: MyP@ssw0rd
​
remember_me
boolean
default:"false"
Extended session duration flag.When false:
  • Access token expires in 15 minutes (900 seconds)
  • Refresh token expires in 7 days (604800 seconds)
When true:
  • Access token expires in 24 hours (86400 seconds)
  • Refresh token expires in 30 days (2592000 seconds)

​
Response

​
access_token
string
JWT access token for authenticating API requests.Use this token in the Authorization header: Authorization: Bearer {access_token}
​
refresh_token
string
JWT refresh token for obtaining new access tokens when they expire.Store this securely on the client side. Use with the Refresh Token endpoint.
​
token_type
string
Token type for the Authorization header.Value: "bearer"
​
expires_in
integer
Access token expiration time in seconds.Values:
  • 900 (15 minutes) when remember_me=false
  • 86400 (24 hours) when remember_me=true
​
user
object
User information object.

​
Example Request

cURL
curl -X POST https://api.softbee.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "password": "MySecure@Pass123",
    "remember_me": true
  }'
Python
import requests

url = "https://api.softbee.com/api/v1/auth/login"
payload = {
    "email": "john.doe@example.com",
    "password": "MySecure@Pass123",
    "remember_me": True
}

response = requests.post(url, json=payload)
data = response.json()

# Store tokens securely
access_token = data['access_token']
refresh_token = data['refresh_token']

print(f"Logged in as: {data['user']['username']}")
JavaScript
fetch('https://api.softbee.com/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'john.doe@example.com',
    password: 'MySecure@Pass123',
    remember_me: true
  })
})
.then(response => response.json())
.then(data => {
  // Store tokens securely (e.g., httpOnly cookies or secure storage)
  localStorage.setItem('access_token', data.access_token);
  localStorage.setItem('refresh_token', data.refresh_token);
  console.log('Logged in:', data.user);
});

​
Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJlbWFpbCI6ImpvaG4uZG9lQGV4YW1wbGUuY29tIiwidXNlcm5hbWUiOiJqb2huX2RvZSIsImlzX3ZlcmlmaWVkIjp0cnVlLCJleHAiOjE3MDk3MzQ4NDV9.xyz...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJleHAiOjE3MTIyMzk2NDV9.abc...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "username": "john_doe",
    "is_verified": true,
    "is_active": true
  }
}

​
Error Responses

{
  "error": "Email validation error: invalid email format"
}

​
Security Features

​
Failed Login Tracking

The system tracks failed login attempts:
  • Increments failure counter on invalid password
  • Resets counter on successful login
  • Account may be locked after multiple failures

​
Account Lockout

After multiple failed login attempts, accounts are temporarily locked to prevent brute force attacks. Contact support to unlock your account.

​
Token Security

  • Access Token: Include in API requests via Authorization: Bearer {token} header
  • Refresh Token: Store securely, use only for obtaining new access tokens
  • Never share tokens or commit them to version control

​
Using the Access Token

Include the access token in subsequent API requests: 
curl -X GET https://api.softbee.com/api/v1/apiaries \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Token Expiration

When your access token expires:
  1. The API will return a 401 Unauthorized response
  2. Use the Refresh Token endpoint to get a new access token
  3. If the refresh token is also expired, the user must log in again

Refresh Token

Learn how to refresh expired access tokens

Build docs developers (and LLMs) love

Get started for freeTalk to us