Login

POST

auth

curl --request POST \
  --url https://auth.nullpass.xyz/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jsmith@example.com",
  "password": "<string>",
  "verificationCode": "<string>"
}
'

import requests

url = "https://auth.nullpass.xyz/api/auth/login"

payload = {
    "email": "jsmith@example.com",
    "password": "<string>",
    "verificationCode": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: 'jsmith@example.com',
    password: '<string>',
    verificationCode: '<string>'
  })
};

fetch('https://auth.nullpass.xyz/api/auth/login', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://auth.nullpass.xyz/api/auth/login",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'jsmith@example.com',
    'password' => '<string>',
    'verificationCode' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://auth.nullpass.xyz/api/auth/login"

	payload := strings.NewReader("{\n  \"email\": \"jsmith@example.com\",\n  \"password\": \"<string>\",\n  \"verificationCode\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://auth.nullpass.xyz/api/auth/login")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"jsmith@example.com\",\n  \"password\": \"<string>\",\n  \"verificationCode\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://auth.nullpass.xyz/api/auth/login")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"jsmith@example.com\",\n  \"password\": \"<string>\",\n  \"verificationCode\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "user": {
    "id": "<string>",
    "email": "jsmith@example.com",
    "username": "<string>",
    "displayName": "<string>",
    "avatar": "<string>",
    "twoFactorEnabled": true,
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "token": "<string>",
  "services": [
    {
      "id": "<string>",
      "userId": "<string>",
      "tier": "premium",
      "isPremium": true,
      "accessFlags": {},
      "metadata": {},
      "customStorageLimit": 123,
      "customApiKeyLimit": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "banned": true,
  "disabled": true
}

{
  "error": "<string>",
  "message": "<string>"
}

Endpoint

POST /api/auth/login

Overview

Authenticates a user with email and password. If 2FA is enabled, returns a pending token that requires verification code. Otherwise, returns a full JWT token and user’s service access information.

Request

string

required

User email address

string

required

User password

string

Required if 2FA is enabled. TOTP code from authenticator app.

Response (Without 2FA or Valid Code)

object

Authenticated user object

Show User Object

string

User ID

string

User email

string

Display name

string

Avatar URL (if set)

string

JWT token for authentication

array

Array of user’s service entitlements

Show Service Entitlement

string

Entitlement ID

string

User ID

string

Service identifier: DROP, MAILS, VAULT, or DB

boolean

Whether service is enabled

string

Expiration date (ISO timestamp) or null

boolean

Whether the user account is banned

boolean

Whether the user account is disabled

Response (2FA Required)

object

Partial user object (without sensitive data)

boolean

Always true when 2FA is required

string

Temporary token for 2FA verification. Not a full JWT token.

string

“2FA verification required”

Implementation Details

Process Flow

CORS & Arcjet: Validates CORS and applies rate limiting
User Lookup: Finds user with service access included
Password Verification: Compares password with bcrypt hash
2FA Check: If enabled, validates verification code or returns pending token
Session Management:
- Reuses existing session if valid and from same IP
- Creates new session if none exists
- Updates expiration on existing sessions
Audit Logging: Logs USER_LOGIN and SESSION_CREATE (if new session)

Code Reference

export async function POST(request: NextRequest) {
  const corsResponse = handleCors(request)
  if (corsResponse) return corsResponse

  const blocked = await protectRoute(request, { requested: 2 })
  if (blocked) return blocked

  try {
    const body = await request.json()
    const validated = loginSchema.parse(body)

    logger.ups('Login attempt:', validated.email)

    const user = await prisma.user.findUnique({
      where: { email: validated.email },
      include: {
        serviceAccess: true,
      },
    })

    if (!user || !user.passwordHash) {
      logger.warn('Login failed: Invalid credentials', validated.email)
      return errorResponse('Invalid credentials', 401, request.headers.get('origin'))
    }

    const isValid = await bcrypt.compare(validated.password, user.passwordHash)
    if (!isValid) {
      logger.warn('Login failed: Invalid password', validated.email)
      return errorResponse('Invalid credentials', 401, request.headers.get('origin'))
    }

    const verificationCode = validated.verificationCode

    if (user.twoFactorEnabled) {
      if (!verificationCode) {
        const pendingToken = generateToken({ userId: user.id, email: user.email })
        return jsonResponse(
          {
            user: {
              id: user.id,
              email: user.email,
              displayName: user.displayName,
              avatar: user.avatar,
            },
            requires2FA: true,
            pendingToken,
            message: '2FA verification required',
          },
          200,
          request.headers.get('origin')
        )
      }

      if (!user.twoFactorSecret) {
        logger.warn('2FA enabled but no secret found', user.id)
        return errorResponse('2FA configuration error', 500, request.headers.get('origin'))
      }

      const verified = speakeasy.totp.verify({
        secret: user.twoFactorSecret,
        encoding: 'base32',
        token: verificationCode,
        window: 2,
      })

      if (!verified) {
        logger.warn('2FA verification failed', user.id)
        return errorResponse('Invalid 2FA verification code', 401, request.headers.get('origin'))
      }
    }

    const clientIp = getClientIp(request)
    const encryptedIp = getClientIpForStorage(request, user.id)

    const existingSession = await prisma.session.findFirst({
      where: {
        userId: user.id,
        ip: encryptedIp,
        expiresAt: {
          gt: new Date(),
        },
      },
      orderBy: {
        createdAt: 'desc',
      },
    })

    let token: string
    const expiresAt = getSessionExpiresAt()

    let sessionCreated = false
    
    if (existingSession) {
      const { verifyToken } = await import('@/lib/auth')
      const tokenPayload = verifyToken(existingSession.token)
      
      if (tokenPayload && tokenPayload.userId === user.id) {
        token = existingSession.token
        await prisma.session.update({
          where: { id: existingSession.id },
          data: {
            expiresAt,
          },
        })
      } else {
        token = generateToken({ userId: user.id, email: user.email })
        await prisma.session.update({
          where: { id: existingSession.id },
          data: {
            token,
            expiresAt,
          },
        })
      }
    } else {
      token = generateToken({ userId: user.id, email: user.email })
      await prisma.session.create({
        data: {
          userId: user.id,
          token,
          expiresAt,
          ip: encryptedIp,
        },
      })
      sessionCreated = true
    }

    await prisma.user.update({
      where: { id: user.id },
      data: { updatedAt: new Date() },
    })

    await createAuditLog(user.id, 'USER_LOGIN', {
      ip: encryptedIp,
      twoFactorUsed: user.twoFactorEnabled && !!verificationCode,
    })
    
    if (sessionCreated) {
      await createAuditLog(user.id, 'SESSION_CREATE', {
        ip: encryptedIp,
      })
    }

    return jsonResponse(
      {
        user: {
          id: user.id,
          email: user.email,
          displayName: user.displayName,
          avatar: user.avatar,
        },
        token,
        services: user.serviceAccess,
      },
      200,
      request.headers.get('origin')
    )
  } catch (error: any) {
    if (error.name === 'ZodError') {
      logger.warn('Login validation error:', error.errors)
      return errorResponse(error.errors[0].message, 400, request.headers.get('origin'))
    }
    logger.error('Login error:', error)
    return errorResponse('Internal server error', 500, request.headers.get('origin'))
  }
}

Status Codes

Bad Request

Validation error

Unauthorized

Invalid credentials or invalid 2FA code

Forbidden

Blocked by Arcjet

Internal Server Error

Server error or 2FA configuration error

Example Requests

Without 2FA

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

With 2FA

# Step 1: Initial login (returns requires2FA: true)
curl -X POST https://auth.nullpass.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'

# Step 2: Verify with 2FA code
curl -X POST https://auth.nullpass.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "verificationCode": "123456"
  }'

Session Reuse Logic

The endpoint implements smart session reuse:

If a valid session exists for the user from the same IP, it reuses the token
Session expiration is updated on reuse
New sessions are only created when none exist or existing session is invalid

Audit Events

USER_LOGIN: Successful login (includes twoFactorUsed flag)
SESSION_CREATE: New session created (only if new session was created)

Body

application/json

string<email>

required

password

string

required

verificationCode

string

Required if 2FA is enabled

Response

Option 1
Option 2

user

object

Show child attributes

token

string

services

object[]

Show child attributes

banned

boolean

Whether the user account is banned

disabled

boolean

Whether the user account is disabled

curl --request POST \
  --url https://auth.nullpass.xyz/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jsmith@example.com",
  "password": "<string>",
  "verificationCode": "<string>"
}
'

import requests

url = "https://auth.nullpass.xyz/api/auth/login"

payload = {
    "email": "jsmith@example.com",
    "password": "<string>",
    "verificationCode": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: 'jsmith@example.com',
    password: '<string>',
    verificationCode: '<string>'
  })
};

fetch('https://auth.nullpass.xyz/api/auth/login', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://auth.nullpass.xyz/api/auth/login",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'jsmith@example.com',
    'password' => '<string>',
    'verificationCode' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://auth.nullpass.xyz/api/auth/login"

	payload := strings.NewReader("{\n  \"email\": \"jsmith@example.com\",\n  \"password\": \"<string>\",\n  \"verificationCode\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://auth.nullpass.xyz/api/auth/login")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"jsmith@example.com\",\n  \"password\": \"<string>\",\n  \"verificationCode\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://auth.nullpass.xyz/api/auth/login")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"jsmith@example.com\",\n  \"password\": \"<string>\",\n  \"verificationCode\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "user": {
    "id": "<string>",
    "email": "jsmith@example.com",
    "username": "<string>",
    "displayName": "<string>",
    "avatar": "<string>",
    "twoFactorEnabled": true,
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "token": "<string>",
  "services": [
    {
      "id": "<string>",
      "userId": "<string>",
      "tier": "premium",
      "isPremium": true,
      "accessFlags": {},
      "metadata": {},
      "customStorageLimit": 123,
      "customApiKeyLimit": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "banned": true,
  "disabled": true
}

{
  "error": "<string>",
  "message": "<string>"
}

Get Started

Authentication

Services

Webhooks

Account Management

Service Connection

Polar Integration

Admin

Advanced

Library

Endpoint

Overview

Request

Response (Without 2FA or Valid Code)

Response (2FA Required)

Implementation Details

Process Flow

Code Reference

Status Codes

Example Requests

Without 2FA

With 2FA

Session Reuse Logic

Audit Events

Body

Response

​Endpoint

​Overview

​Request

​Response (Without 2FA or Valid Code)

​Response (2FA Required)

​Implementation Details

​Process Flow

​Code Reference

​Status Codes

​Example Requests

​Without 2FA

​With 2FA

​Session Reuse Logic

​Audit Events

Body

Response

Endpoint

Overview

Request

Response (Without 2FA or Valid Code)

Response (2FA Required)

Implementation Details

Process Flow

Code Reference

Status Codes

Example Requests

Without 2FA

With 2FA

Session Reuse Logic

Audit Events