Quickstart Guide

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"
  }'

const response = await fetch('https://auth.nullpass.xyz/api/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securepassword123',
    displayName: 'John Doe'
  })
});

const data = await response.json();
console.log('Token:', data.token);

import requests

response = requests.post(
    'https://auth.nullpass.xyz/api/auth/register',
    json={
        'email': 'user@example.com',
        'password': 'securepassword123',
        'displayName': 'John Doe'
    }
)

data = response.json()
print(f"Token: {data['token']}")

const response = await fetch('https://auth.nullpass.xyz/api/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securepassword123',
    displayName: 'John Doe'
  })
});

const data: { user: User; token: string } = await response.json();
console.log('Token:', data.token);

object

The created user object

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

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"
  }'

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

const data = await response.json();

if (data.requires2FA) {
  // Handle 2FA flow
  console.log('2FA required. Pending token:', data.pendingToken);
} else {
  console.log('Logged in! Token:', data.token);
  console.log('Services:', data.services);
}

import requests

response = requests.post(
    'https://auth.nullpass.xyz/api/auth/login',
    json={
        'email': 'user@example.com',
        'password': 'securepassword123'
    }
)

data = response.json()

if data.get('requires2FA'):
    print('2FA required. Pending token:', data['pendingToken'])
else:
    print('Logged in! Token:', data['token'])
    print('Services:', data['services'])

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"

const token = 'YOUR_TOKEN_HERE';

const response = await fetch('https://auth.nullpass.xyz/api/auth/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log('User:', data.user);
console.log('Service Access:', data.user.serviceAccess);

import requests

token = 'YOUR_TOKEN_HERE'

response = requests.get(
    'https://auth.nullpass.xyz/api/auth/me',
    headers={
        'Authorization': f'Bearer {token}'
    }
)

data = response.json()
print('User:', data['user'])
print('Service Access:', data['user']['serviceAccess'])

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"
  }'

const token = 'YOUR_TOKEN_HERE';

const response = await fetch('https://auth.nullpass.xyz/api/auth/me', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    displayName: 'Jane Doe',
    avatar: 'https://example.com/avatar.jpg'
  })
});

const data = await response.json();
console.log('Updated user:', data.user);

import requests

token = 'YOUR_TOKEN_HERE'

response = requests.patch(
    'https://auth.nullpass.xyz/api/auth/me',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'displayName': 'Jane Doe',
        'avatar': 'https://example.com/avatar.jpg'
    }
)

data = response.json()
print('Updated user:', data['user'])

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"

const token = 'YOUR_TOKEN_HERE';

// Get all sessions
const sessionsResponse = await fetch(
  'https://auth.nullpass.xyz/api/auth/sessions',
  {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const sessionsData = await sessionsResponse.json();
console.log('Active sessions:', sessionsData.sessions);

// Delete a specific session
await fetch(
  `https://auth.nullpass.xyz/api/auth/sessions?id=${sessionsData.sessions[0].id}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

import requests

token = 'YOUR_TOKEN_HERE'

# Get all sessions
sessions_response = requests.get(
    'https://auth.nullpass.xyz/api/auth/sessions',
    headers={'Authorization': f'Bearer {token}'}
)

sessions_data = sessions_response.json()
print('Active sessions:', sessions_data['sessions'])

# Delete a specific session
session_id = sessions_data['sessions'][0]['id']
requests.delete(
    f'https://auth.nullpass.xyz/api/auth/sessions?id={session_id}',
    headers={'Authorization': f'Bearer {token}'}
)

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"
  }'

const token = 'YOUR_TOKEN_HERE';

// Step 1: Generate QR code
const qrResponse = await fetch('https://auth.nullpass.xyz/api/auth/2fa', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    enable: true
  })
});

const qrData = await qrResponse.json();
console.log('QR Code:', qrData.qrCode);
console.log('Secret:', qrData.secret);

// Step 2: Confirm with verification code from authenticator app
const confirmResponse = await fetch('https://auth.nullpass.xyz/api/auth/2fa', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    enable: true,
    secret: qrData.secret,
    verificationCode: '123456' // From authenticator app
  })
});

const confirmData = await confirmResponse.json();
console.log('2FA enabled:', confirmData.twoFactorEnabled);

import requests

token = 'YOUR_TOKEN_HERE'

# Step 1: Generate QR code
qr_response = requests.post(
    'https://auth.nullpass.xyz/api/auth/2fa',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={'enable': True}
)

qr_data = qr_response.json()
print('QR Code:', qr_data['qrCode'])
print('Secret:', qr_data['secret'])

# Step 2: Confirm with verification code from authenticator app
confirm_response = requests.post(
    'https://auth.nullpass.xyz/api/auth/2fa',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'enable': True,
        'secret': qr_data['secret'],
        'verificationCode': '123456'  # From authenticator app
    }
)

confirm_data = confirm_response.json()
print('2FA enabled:', confirm_data['twoFactorEnabled'])

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

Getting 401 Unauthorized errors

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.

Rate limiting errors (403)

Null Pass uses Arcjet for rate limiting. If you’re hitting limits, implement exponential backoff and consider caching responses where appropriate.

2FA not working

Ensure your system clock is synchronized (NTP). TOTP codes are time-sensitive and require accurate time.

CORS issues

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.

Get Started

Authentication

Services

Webhooks

Account Management

Service Connection

Polar Integration

Admin

Advanced

Library

Introduction

Prerequisites

Step 1: Register a User

Step 3: Get User Profile

Step 4: Update Profile

Step 5: Manage Sessions

Step 6: Enable Two-Factor Authentication

Next Steps

Service Management

Webhooks

Error Handling

Rate Limiting

Common Issues

​Introduction

​Prerequisites

​Step 1: Register a User

​Step 2: Login

​Step 3: Get User Profile

​Step 4: Update Profile

​Step 5: Manage Sessions

​Step 6: Enable Two-Factor Authentication

​Next Steps

Service Management

Webhooks

Error Handling

Rate Limiting

​Common Issues

Introduction

Prerequisites

Step 1: Register a User

Step 2: Login

Step 3: Get User Profile

Step 4: Update Profile

Step 5: Manage Sessions

Step 6: Enable Two-Factor Authentication

Next Steps

Common Issues