Skip to content

Authentication API

All API requests require authentication using a Bearer token. This section covers all authentication-related endpoints.

Login

Authenticates a user and returns access and refresh tokens.

POST https://api.darukaa.com/auth/login

HTTP request

POST https://api.darukaa.com/auth/login

Request body

The request body contains data with the following structure:

{
  "email": "string",
  "password": "string"
}
Field Type Required Description
email string Yes User's email address used to authenticate. Must be registered in the system.
password string Yes User's account password.

Example request

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

import requests

url = "https://api.darukaa.com/auth/login"
payload = {
    "email": "user@example.com",
    "password": "your_password"
}

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

access_token = data["access_token"]
refresh_token = data["refresh_token"]

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

const data = await response.json();
const accessToken = data.access_token;
const refreshToken = data.refresh_token;

Status codes

Code Description
200 Success - Authentication successful
401 Unauthorized - Invalid email or password

Response body

Success (200)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "active",
  "is_email_verified": true
}
Field Type Description
access_token string (JWT) Short-lived access token for authenticated requests
refresh_token string Long-lived token for obtaining new access tokens
email string User's email address
first_name string User's first name
last_name string User's last name
status string Account status (e.g., active)
is_email_verified boolean Whether the user's email is verified

Failure (401)

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password",
    "details": "The provided credentials do not match any account",
    "request_id": "req_abc123",
    "timestamp": "2025-12-04T13:30:00Z"
  }
}

Sign Up

Creates a new user account.

HTTP request

POST https://api.darukaa.com/api/v1/auth/signup

Request body

The request body contains data with the following structure:

{
  "email": "string",
  "password": "string",
  "first_name": "string",
  "last_name": "string",
  "tnc_checked": true
}
Field Type Required Description
email string Yes Email address for the new account. Must be unique and valid.
password string Yes Account password. Enforce your password policy (min length, complexity) on the server.
first_name string No User's given name. Optional but recommended for personalization.
last_name string No User's family name. Optional.
tnc_checked boolean Yes Must be true to indicate the user accepted Terms & Conditions. Signup should be rejected if false.

Example request

curl -X POST https://api.darukaa.com/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure_password123",
    "first_name": "Jane",
    "last_name": "Smith",
    "tnc_checked": true
  }'

import requests

url = "https://api.darukaa.com/api/v1/auth/signup"
payload = {
    "email": "newuser@example.com",
    "password": "secure_password123",
    "first_name": "Jane",
    "last_name": "Smith",
    "tnc_checked": True
}

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

const response = await fetch('https://api.darukaa.com/api/v1/auth/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'newuser@example.com',
    password: 'secure_password123',
    first_name: 'Jane',
    last_name: 'Smith',
    tnc_checked: true
  })
});

Status codes

Code Description
201 Success - Account created successfully
400 Bad Request - Invalid input data or email already exists

Response body

Success (201)

"Please verify your email to complete signup"

Failure (400)

{
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "message": "An account with this email already exists",
    "details": "Please use a different email address or try logging in",
    "request_id": "req_abc123",
    "timestamp": "2025-12-04T13:30:00Z"
  }
}

Refresh Token

Obtains a new access token when the current one expires.

HTTP request

POST https://api.darukaa.com/auth/refresh

Headers

Header Value Required
Authorization Bearer Yes

Example request

curl -X POST https://api.darukaa.com/auth/refresh \
  -H "Authorization: Bearer <your_refresh_token>"

import requests

headers = {"Authorization": f"Bearer {refresh_token}"}
response = requests.post(
    "https://api.darukaa.com/auth/refresh",
    headers=headers
)
data = response.json()

const response = await fetch('https://api.darukaa.com/auth/refresh', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${refreshToken}`
  }
});

const data = await response.json();

Status codes

Code Description
200 Success - New access token issued
401 Unauthorized - Invalid or expired refresh token

Response body

Success (200)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "active",
  "is_email_verified": true
}
Field Type Description
access_token string (JWT) New short-lived access token to use for authenticated requests
refresh_token string (Optional) A rotated/renewed refresh token. If your implementation rotates refresh tokens, return the new one
email string User email associated with tokens
first_name string User's first name
last_name string User's last name
status string Account status
is_email_verified boolean Whether the user's email is verified

Failure (401)

{
  "error": {
    "code": "INVALID_REFRESH_TOKEN",
    "message": "Invalid or expired refresh token",
    "details": "Please login again to obtain a new refresh token",
    "request_id": "req_abc123",
    "timestamp": "2025-12-04T13:30:00Z"
  }
}

Get Current User

Retrieves information about the currently authenticated user.

HTTP request

GET https://api.darukaa.com/api/v1/auth/user

Headers

Header Value Required
Authorization Bearer Yes

Example request

curl -X GET https://api.darukaa.com/api/v1/auth/user \
  -H "Authorization: Bearer <your_access_token>"

import requests

headers = {
    "Authorization": f"Bearer {access_token}"
}

response = requests.get(
    "https://api.darukaa.com/api/v1/auth/user",
    headers=headers
)

user_info = response.json()

const response = await fetch('https://api.darukaa.com/api/v1/auth/user', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const userInfo = await response.json();

Status codes

Code Description
200 Success - User information retrieved
401 Unauthorized - Invalid or missing access token

Response body

Success (200)

{
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "Active",
  "is_email_verified": false
}
Field Type Description
email string Registered email address of the user
first_name string User's first name
last_name string User's last name
status string Account status (Active/Suspended/etc.)
is_email_verified boolean Indicates whether the email has been verified

Failure (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing access token",
    "details": "Please provide a valid Bearer token in the Authorization header",
    "request_id": "req_abc123",
    "timestamp": "2025-12-04T13:30:00Z"
  }
}

Update Current User

Updates information for the currently authenticated user.

HTTP request

PUT https://api.darukaa.com/api/v1/auth/user

Headers

Header Value Required
Authorization Bearer Yes

Request body

The request body contains data with the following structure:

{
  "first_name": "string",
  "last_name": "string",
  "password": "string"
}
Field Type Required Description
first_name string No Optional field to update the first name
last_name string No Optional field to update the last name
password string No Used to update the account password. Recommend minimum length & complexity

Example request

curl -X PUT https://api.darukaa.com/api/v1/auth/user \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith"
  }'

import requests

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}
payload = {
    "first_name": "Jane",
    "last_name": "Smith"
}

response = requests.put(
    "https://api.darukaa.com/api/v1/auth/user",
    headers=headers,
    json=payload
)
user_info = response.json()

const response = await fetch('https://api.darukaa.com/api/v1/auth/user', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'Jane',
    last_name: 'Smith'
  })
});

const userInfo = await response.json();

Status codes

Code Description
200 Success - User information updated
401 Unauthorized - Invalid or missing access token

Response body

Success (200)

{
  "email": "user@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "status": "Active",
  "is_email_verified": false
}
Field Type Description
email string Registered email of the user
first_name string Updated first name
last_name string Updated last name
status string Account status
is_email_verified boolean Whether the email is verified

Failure (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing access token",
    "details": "Please provide a valid Bearer token in the Authorization header",
    "request_id": "req_abc123",
    "timestamp": "2025-12-04T13:30:00Z"
  }
}

Logout

Invalidates the current refresh token.

HTTP request

POST https://api.darukaa.com/api/v1/auth/logout

Headers

Header Value Required
Authorization Bearer Yes

Example request

curl -X POST https://api.darukaa.com/api/v1/auth/logout \
  -H "Authorization: Bearer <your_refresh_token>"

import requests

headers = {"Authorization": f"Bearer {refresh_token}"}
response = requests.post(
    "https://api.darukaa.com/api/v1/auth/logout",
    headers=headers
)
result = response.json()

const response = await fetch('https://api.darukaa.com/api/v1/auth/logout', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${refreshToken}`
  }
});

const result = await response.json();

Status codes

Code Description
200 Success - Logout successful
401 Unauthorized - Invalid refresh token

Response body

Success (200)

{
  "msg": "Successfully logged out"
}

Failure (401)

{
  "error": {
    "code": "INVALID_REFRESH_TOKEN",
    "message": "Invalid or expired refresh token",
    "details": "The refresh token provided is not valid",
    "request_id": "req_abc123",
    "timestamp": "2025-12-04T13:30:00Z"
  }
}