> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nullpass.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Internal development setup and testing guide

<Warning>
  **Internal Documentation Only:** If you're not a Null Tools developer, you can close this documentation or visit the [Apps section](/apps/coming-soon) to learn more about using Null Pass in your applications.
</Warning>

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

<ResponseField name="user" type="object">
  The created user object
</ResponseField>

<ResponseField name="token" type="string">
  JWT token for authentication. Store this securely!
</ResponseField>

<Warning>
  **Password Requirements:**

  * Minimum 8 characters
  * Store passwords securely - never log or expose them
  * Use HTTPS in production
</Warning>

## Step 2: Login

Now let's authenticate an existing user:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://auth.nullpass.xyz/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "password": "securepassword123"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

<Note>
  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.
</Note>

## Step 3: Get User Profile

Use the token from login/register to fetch the authenticated user's profile:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://auth.nullpass.xyz/api/auth/me \
    -H "Authorization: Bearer YOUR_TOKEN_HERE"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

## Step 4: Update Profile

Update the user's display name or avatar:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

## Step 5: Manage Sessions

View and manage active sessions:

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```javascript JavaScript theme={null}
  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}`
      }
    }
  );
  ```

  ```python Python theme={null}
  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}'}
  )
  ```
</CodeGroup>

## Step 6: Enable Two-Factor Authentication

Secure your account with 2FA:

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

<Tip>
  Use an authenticator app like Google Authenticator, Authy, or 1Password to scan the QR code and generate verification codes.
</Tip>

## Next Steps

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

<CardGroup cols={2}>
  <Card title="Service Management" icon="server" href="/api-reference/services/overview">
    Learn how to manage service entitlements for DROP, MAILS, VAULT, and DB
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    Set up webhooks to receive real-time notifications
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/advanced/error-handling">
    Understand error responses and how to handle them
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/api-reference/advanced/rate-limiting">
    Learn about rate limits and best practices
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="2FA not working">
    Ensure your system clock is synchronized (NTP). TOTP codes are time-sensitive and require accurate time.
  </Accordion>

  <Accordion title="CORS issues">
    The API supports CORS. Make sure you're making requests from an allowed origin or include proper CORS headers in your requests.
  </Accordion>
</AccordionGroup>

<Note>
  Need more help? Check out our [API Reference](/api-reference/auth/register) or [contact support](https://nullpass.xyz/support).
</Note>