Skip to main content
Internal Documentation Only: If you’re not a Null Tools developer, you can close this documentation or visit the Apps section to learn more about using Null Pass in your applications.

​
Introduction

This guide covers setting up the Null Pass development environment, running the API locally, and testing endpoints. This is internal documentation for developers working on the Null Pass system.

​
Prerequisites

  • Node.js 18+ installed
  • PostgreSQL database
  • Git access to the repository
  • Environment variables configured

​
Step 1: Register a User

First, let’s create a new user account. This endpoint will create a user and return a JWT token for authentication. 
curl -X POST https://auth.nullpass.xyz/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "displayName": "John Doe"
  }'
​
user
object
The created user object
​
token
string
JWT token for authentication. Store this securely!
Password Requirements:
  • Minimum 8 characters
  • Store passwords securely - never log or expose them
  • Use HTTPS in production

​
Step 2: Login

Now let’s authenticate an existing user: 
curl -X POST https://auth.nullpass.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'
If the user has 2FA enabled, you’ll receive a requires2FA: true response. You’ll need to prompt for the verification code and include it in a subsequent request.

​
Step 3: Get User Profile

Use the token from login/register to fetch the authenticated user’s profile: 
curl -X GET https://auth.nullpass.xyz/api/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

​
Step 4: Update Profile

Update the user’s display name or avatar: 
curl -X PATCH https://auth.nullpass.xyz/api/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Jane Doe",
    "avatar": "https://example.com/avatar.jpg"
  }'

​
Step 5: Manage Sessions

View and manage active sessions: 
# Get all sessions
curl -X GET https://auth.nullpass.xyz/api/auth/sessions \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

# Delete a specific session
curl -X DELETE https://auth.nullpass.xyz/api/auth/sessions?id=session_id \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

# Delete all sessions
curl -X DELETE https://auth.nullpass.xyz/api/auth/sessions \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

​
Step 6: Enable Two-Factor Authentication

Secure your account with 2FA: 
# Step 1: Generate QR code
curl -X POST https://auth.nullpass.xyz/api/auth/2fa \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "enable": true
  }'

# Step 2: Confirm with verification code
curl -X POST https://auth.nullpass.xyz/api/auth/2fa \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "enable": true,
    "secret": "SECRET_FROM_STEP_1",
    "verificationCode": "123456"
  }'
Use an authenticator app like Google Authenticator, Authy, or 1Password to scan the QR code and generate verification codes.

​
Next Steps

Now that you have the basics working, explore these advanced features:

Service Management

Learn how to manage service entitlements for DROP, MAILS, VAULT, and DB

Webhooks

Set up webhooks to receive real-time notifications

Error Handling

Understand error responses and how to handle them

Rate Limiting

Learn about rate limits and best practices

​
Common Issues

Make sure you’re including the Authorization header with a valid Bearer token. Tokens expire after 7 days - you may need to log in again.
Null Pass uses Arcjet for rate limiting. If you’re hitting limits, implement exponential backoff and consider caching responses where appropriate.
Ensure your system clock is synchronized (NTP). TOTP codes are time-sensitive and require accurate time.
The API supports CORS. Make sure you’re making requests from an allowed origin or include proper CORS headers in your requests.
Need more help? Check out our API Reference or contact support.