### Start Production Server

Source: https://context7.com/fosrl/pangolin/llms.txt

Starts the production server, first running database migrations and then starting the Express application.

```bash
npm run start
```

--------------------------------

### Run Development Server

Source: https://context7.com/fosrl/pangolin/llms.txt

Starts the development server with hot-reloading enabled using tsx watch.

```bash
npm run dev
```

--------------------------------

### Security Key Registration Start API Endpoint

Source: https://context7.com/fosrl/pangolin/llms.txt

Starts the process for registering a hardware security key (WebAuthn) for an authenticated user. Rate-limited.

```bash
# Start passkey/security key registration (requires active session)
curl -b cookies.txt -X POST https://dash.example.com/api/v1/auth/security-key/register/start
# Returns WebAuthn PublicKeyCredentialCreationOptions

```

--------------------------------

### Start authentication (no session required)

Source: https://context7.com/fosrl/pangolin/llms.txt

Initiates the security key authentication process without requiring an existing session.

```APIDOC
## POST /api/v1/auth/security-key/authenticate/start

### Description
Starts the security key authentication flow. This endpoint does not require an active session.

### Method
POST

### Endpoint
/api/v1/auth/security-key/authenticate/start

### Request Body
- **email** (string) - Required - The email address of the user to authenticate.
```

--------------------------------

### Clone Pangolin Repository and Install Dependencies

Source: https://context7.com/fosrl/pangolin/llms.txt

Clone the Pangolin repository from GitHub and install all necessary project dependencies using npm.

```bash
# Clone and install dependencies
git clone https://github.com/fosrl/pangolin
npm install
```

--------------------------------

### Run Ephemeral Postgres Database with Docker

Source: https://github.com/fosrl/pangolin/blob/main/server/db/README.md

Start a temporary Postgres database instance for local development using Docker. This command ensures the container is removed upon stopping.

```bash
docker run -d \
  --name postgres \
  --rm \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  -v $(mktemp -d):/var/lib/postgresql/data \
  postgres:17
```

--------------------------------

### Get Server Information

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieve information about the Pangolin server, including its version, build type, and enabled feature flags.

```bash
curl -b cookies.txt https://dash.example.com/api/v1/server-info
# {
#   "data": {
#     "version": "1.18.0",
#     "build": "oss",
#     "flags": {
#       "emailEnabled": false,
#       "signupWithoutInviteDisabled": true
#     }
#   }
# }
```

--------------------------------

### TOTP Secret Request and Enable API Endpoints

Source: https://context7.com/fosrl/pangolin/llms.txt

Initiates TOTP setup, returning a secret and QR code. Requires a subsequent call with a valid code to enable 2FA.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/auth/2fa/request
# 200 OK → {"data": {"secret": "BASE32SECRET", "qrCode": "data:image/png;base64,..."}}

# Verify and activate 2FA with a valid code:
curl -b cookies.txt -X POST https://dash.example.com/api/v1/auth/2fa/enable \
  -H "Content-Type: application/json" \
  -d '{"code": "654321"}'
# 200 OK → 2FA enabled

# Disable 2FA:
curl -b cookies.txt -X POST https://dash.example.com/api/v1/auth/2fa/disable \
  -H "Content-Type: application/json" \
  -d '{"code": "654321"}'

```

--------------------------------

### Get Organization Overview

Source: https://context7.com/fosrl/pangolin/llms.txt

Fetches aggregate statistics for an organization, including counts of sites, resources, users, and recent activity.

```bash
curl -b cookies.txt https://dash.example.com/api/v1/org/my-company/overview
```

--------------------------------

### Initiate Device Web Authentication

Source: https://context7.com/fosrl/pangolin/llms.txt

Starts a device-based web authentication flow, returning a short-lived code for CLI/client authentication via browser. This code is used for subsequent polling.

```bash
curl -X POST https://dash.example.com/api/v1/auth/device-web-auth/start
```

--------------------------------

### Complete Device Web Authentication

Source: https://context7.com/fosrl/pangolin/llms.txt

Verifies the device web authentication flow after user approval in the browser. Requires the code obtained during the start phase.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/auth/device-web-auth/verify \
  -H "Content-Type: application/json" \
  -d '{"code": "ABC123"}'
```

--------------------------------

### Generate and Push Postgres Database Migrations

Source: https://github.com/fosrl/pangolin/blob/main/server/db/README.md

Commands to generate database schema changes and push them to the Postgres database. Ensure drizzle-kit is installed and a connection string is configured.

```bash
npm run db:generate
npm run db:push
```

--------------------------------

### Two-Factor Authentication (2FA) Management

Source: https://context7.com/fosrl/pangolin/llms.txt

Manages TOTP 2FA setup, including requesting a secret, enabling, and disabling.

```APIDOC
## POST /api/v1/auth/2fa/request — Request TOTP Secret

### Description
Initiates TOTP setup for the authenticated user. Returns a TOTP secret and QR code data.

### Method
POST

### Endpoint
/api/v1/auth/2fa/request

### Response
#### Success Response (200)
- **data** (object)
  - **secret** (string) - The base32 encoded TOTP secret.
  - **qrCode** (string) - Data URL for the QR code representing the TOTP setup.

#### Response Example
```json
{
  "data": {
    "secret": "BASE32SECRET",
    "qrCode": "data:image/png;base64,மையில்..."
  },
  "success": true
}
```

## POST /api/v1/auth/2fa/enable — Enable 2FA

### Description
Verifies a TOTP code and enables 2FA for the authenticated user.

### Method
POST

### Endpoint
/api/v1/auth/2fa/enable

### Request Body
- **code** (string) - Required - The valid TOTP code.

### Request Example
```json
{
  "code": "654321"
}
```

### Response
#### Success Response (200)
Indicates that 2FA has been successfully enabled.

## POST /api/v1/auth/2fa/disable — Disable 2FA

### Description
Disables 2FA for the authenticated user using a valid TOTP code.

### Method
POST

### Endpoint
/api/v1/auth/2fa/disable

### Request Body
- **code** (string) - Required - The valid TOTP code.

### Request Example
```json
{
  "code": "654321"
}
```

### Response
#### Success Response (200)
Indicates that 2FA has been successfully disabled.
```

--------------------------------

### Get Organization Details

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieves details for a specific organization, identified by its orgId. Returns information including subnet and domains.

```bash
curl -b cookies.txt https://dash.example.com/api/v1/org/my-company
```

--------------------------------

### GET /api/v1/org/:orgId/overview — Organization Overview

Source: https://context7.com/fosrl/pangolin/llms.txt

Fetches aggregate statistics for an organization, including counts of sites, resources, users, and recent activity.

```APIDOC
## GET /api/v1/org/:orgId/overview

### Description
Returns aggregate statistics for the organization, such as the number of sites, resources, and users, as well as recent activity.

### Method
GET

### Endpoint
/api/v1/org/:orgId/overview

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The ID of the organization for which to retrieve the overview.
```

--------------------------------

### GET /api/v1/org/:orgId — Get Organization

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieves detailed information about a specific organization.

```APIDOC
## GET /api/v1/org/:orgId

### Description
Retrieves detailed information about a specific organization, including its subnet, assigned domains, and creation date.

### Method
GET

### Endpoint
/api/v1/org/:orgId

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The ID of the organization to retrieve.
```

--------------------------------

### Initialize Development Environment for OSS + SQLite

Source: https://context7.com/fosrl/pangolin/llms.txt

Set up the development environment for Pangolin, specifically configured for the Open Source Software (OSS) version with SQLite database.

```bash
# Initialize for OSS + SQLite development
npm run dev:setup
```

--------------------------------

### Open Drizzle Studio

Source: https://context7.com/fosrl/pangolin/llms.txt

Opens Drizzle Studio, a local database browser, for database management.

```bash
npm run db:studio
```

--------------------------------

### GET /api/v1/org/:orgId/sites — List Sites

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieves a list of all sites within a specified organization.

```APIDOC
## GET /api/v1/org/:orgId/sites

### Description
Retrieves a list of all sites belonging to the specified organization. The response includes details such as status, type, subnet, and online state for each site.

### Method
GET

### Endpoint
/api/v1/org/:orgId/sites

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The ID of the organization whose sites are to be listed.
```

--------------------------------

### Build for Production

Source: https://context7.com/fosrl/pangolin/llms.txt

Builds the project for production using Next.js and esbuild for server bundling.

```bash
npm run build
```

--------------------------------

### Build CLI Tool

Source: https://context7.com/fosrl/pangolin/llms.txt

Builds the command-line interface tool for the project.

```bash
npm run build:cli
```

--------------------------------

### POST /api/v1/auth/device-web-auth/start — Device Web Auth

Source: https://context7.com/fosrl/pangolin/llms.txt

Initiates a device-based web authentication flow. Returns a short-lived code for client polling until user approval in the browser.

```APIDOC
## POST /api/v1/auth/device-web-auth/start

### Description
Initiates a device-based web authentication flow. This is useful for CLI or client authentication via a browser. It returns a short-lived code that a Pangolin client can poll until a user approves the authentication in their browser.

### Method
POST

### Endpoint
/api/v1/auth/device-web-auth/start

### Response
#### Success Response (200)
- **data** (object) - Contains the authentication code and verification URL.
  - **code** (string) - A short-lived code for polling.
  - **verificationUrl** (string) - The URL where the user can approve the authentication.
```

--------------------------------

### GET /api/v1/org/:orgId/users — List Users

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieves a list of users within a specified organization, with support for pagination.

```APIDOC
## GET /api/v1/org/:orgId/users

### Description
Lists users within a specified organization.

### Method
GET

### Endpoint
/api/v1/org/:orgId/users

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **limit** (integer) - Optional - The number of users to return per page.
```

--------------------------------

### Configure Resource Authentication - Email Whitelist with OTP

Source: https://context7.com/fosrl/pangolin/llms.txt

Enables email whitelist authentication and allows adding trusted email addresses. An OTP email will be sent for authentication.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/resource/42/whitelist \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/resource/42/whitelist/add \
  -H "Content-Type: application/json" \
  -d '{"email": "trusted@partner.com"}'
```

--------------------------------

### Accept Invitation via API

Source: https://context7.com/fosrl/pangolin/llms.txt

Use this endpoint to accept an invitation by providing the token, email, and a new password.

```bash
curl -X POST https://dash.example.com/api/v1/invite/accept \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123-xyz",
    "email": "colleague@example.com",
    "password": "NewUserPass123!"
  }'
```

--------------------------------

### GET /api/v1/auth/device-web-auth/poll/:code — Poll for Device Web Auth Approval

Source: https://context7.com/fosrl/pangolin/llms.txt

Polls for the approval status of a device-based web authentication request.

```APIDOC
## GET /api/v1/auth/device-web-auth/poll/:code

### Description
Polls the status of a device-based web authentication request using the provided code. The client should poll this endpoint until the user approves the request in the browser. Note: This endpoint has a rate limit of 60 requests per minute.

### Method
GET

### Endpoint
/api/v1/auth/device-web-auth/poll/:code

### Parameters
#### Path Parameters
- **code** (string) - Required - The short-lived code obtained from the `/start` endpoint.
```

--------------------------------

### Create WireGuard Site

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new site using the 'wireguard' type for raw WireGuard peering. Requires exitNodeId, subnet, and a WireGuard public key.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/org/my-company/site \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office WG",
    "type": "wireguard",
    "exitNodeId": 1,
    "subnet": "10.20.1.0/24",
    "pubKey": "Base64EncodedWireGuardPublicKey="
  }'
```

--------------------------------

### Set Server Admin Credentials using pangctl

Source: https://context7.com/fosrl/pangolin/llms.txt

Configure the initial administrator account for the Pangolin server. This command is run inside the Pangolin container.

```bash
# Inside the container:
node dist/cli.mjs set-admin-credentials \
  --email admin@example.com \
  --password "StrongAdminPass123!"
# Output: "Admin credentials updated successfully"
```

--------------------------------

### Run Linting and Type-Check

Source: https://context7.com/fosrl/pangolin/llms.txt

Executes linting and type-checking for the project.

```bash
npm run dev:check
```

--------------------------------

### Manage API Key Permissions

Source: https://context7.com/fosrl/pangolin/llms.txt

List available actions for an API key or set specific permissions by providing a list of action IDs. Use POST to update permissions.

```bash
# List actions available to an API key
curl -b cookies.txt \
  https://dash.example.com/api/v1/org/my-company/api-key/key_abc123/actions
```

```bash
# Set permissions on a key
curl -b cookies.txt -X POST \
  https://dash.example.com/api/v1/org/my-company/api-key/key_abc123/actions \
  -H "Content-Type: application/json" \
  -d '{"actionIds": ["listSites", "getSite", "listResources"]}'
```

--------------------------------

### Create HTTP Resource

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new HTTP resource with specified configurations.

```APIDOC
## PUT /api/v1/org/my-company/resource

### Description
Creates a new HTTP resource.

### Method
PUT

### Endpoint
https://dash.example.com/api/v1/org/my-company/resource

### Request Body
- **name** (string) - Required - The name of the resource.
- **http** (boolean) - Required - Indicates if the resource is HTTP.
- **protocol** (string) - Required - The protocol used (e.g., "tcp").
- **domainId** (string) - Optional - The domain ID for the resource.
- **subdomain** (string) - Optional - The subdomain for the resource.
- **stickySession** (boolean) - Optional - Whether to enable sticky sessions.
- **postAuthPath** (string) - Optional - The path for post-authentication redirection.

### Request Example
```json
{
  "name": "Grafana Dashboard",
  "http": true,
  "protocol": "tcp",
  "domainId": "primary",
  "subdomain": "grafana",
  "stickySession": false,
  "postAuthPath": "/dashboard"
}
```

### Response
#### Success Response (201 Created)
Returns a Resource object with resourceId, fullDomain, etc.
```

--------------------------------

### Create Newt-based Site

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new site using the 'newt' type for NAT traversal. Requires a name and returns Newt connector credentials.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/org/my-company/site \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home Lab",
    "type": "newt"
  }'
```

--------------------------------

### Apply YAML Blueprint via API

Source: https://context7.com/fosrl/pangolin/llms.txt

Declaratively create or update organization resources (sites, proxies, clients) by submitting a YAML blueprint. This operation is idempotent.

```bash
# Construct the blueprint YAML and POST it
BLUEPRINT=$(cat <<'EOF'
proxy-resources:
  grafana:
    name: Grafana
    protocol: http
    full-domain: grafana.example.com
    ssl: true
    targets:
      - site: home-lab-abc
        method: http
        hostname: 192.168.1.100
        port: 3000
        enabled: true
        healthcheck:
          hostname: 192.168.1.100
          port: 3000
          enabled: true
          path: /api/health
          scheme: http
          interval: 30
          timeout: 5
    auth:
      sso-enabled: true
      sso-roles: ["DevOps"]
    rules:
      - match: cidr
        action: deny
        value: "0.0.0.0/0"
        priority: 1
      - match: cidr
        action: allow
        value: "10.0.0.0/8"
        priority: 2

client-resources:
  ssh-bastion:
    name: SSH Bastion
    mode: host
    destination: 192.168.1.10
    alias: bastion.internal.example.com
    sites: [home-lab-abc]
    tcp-ports: "22"
    roles: ["DevOps"]

sites:
  new-office:
    name: Office Network
    docker-socket-enabled: false
EOF
)

curl -b cookies.txt -X PUT https://dash.example.com/api/v1/org/my-company/blueprint \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Production Stack\", \"blueprint\": $(echo \"$BLUEPRINT\" | jq -Rs .)}"
```

--------------------------------

### Invite User to Organization

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a time-limited invitation link for a user to join an organization with specified roles. Optionally sends an invitation email.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/org/my-company/create-invite \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@example.com",
    "roleIds": [2],
    "validHours": 48,
    "sendEmail": true
  }'
```

--------------------------------

### Configure Resource Authentication - Header

Source: https://context7.com/fosrl/pangolin/llms.txt

Configures header-based authentication, passing a specified header to the upstream. Requires header name and value.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/resource/42/header-auth \
  -H "Content-Type: application/json" \
  -d '{"headerName": "X-Auth-User", "headerValue": "pangolin"}'
```

--------------------------------

### Configure Resource Authentication - Password

Source: https://context7.com/fosrl/pangolin/llms.txt

Sets a simple password for resource authentication. This is a POST request to the resource's password endpoint.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/resource/42/password \
  -H "Content-Type: application/json" \
  -d '{"password": "resourcepassword"}'
```

--------------------------------

### Create HTTP Resource

Source: https://context7.com/fosrl/pangolin/llms.txt

Use this endpoint to create a new HTTP resource. It requires a JSON payload with resource details such as name, protocol, domain, and subdomain.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/org/my-company/resource \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Grafana Dashboard",
    "http": true,
    "protocol": "tcp",
    "domainId": "primary",
    "subdomain": "grafana",
    "stickySession": false,
    "postAuthPath": "/dashboard"
  }'
```

--------------------------------

### User Registration API Endpoint

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new internal user account. Rate-limited and may require an invite token.

```bash
curl -X PUT https://dash.example.com/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{ 
    "email": "newuser@example.com",
    "password": "StrongPass123!",
    "inviteToken": "abc123-token"
  }'
# 201 Created → {"data": null, "success": true, "message": "User created successfully"}

```

--------------------------------

### Create Organization

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new organization with default roles and provisions a SSH CA key pair. Requires organization ID, name, and subnet details.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/org \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "my-company",
    "name": "My Company",
    "subnet": "10.10.0.0/16",
    "utilitySubnet": "10.11.0.0/24"
  }'
```

--------------------------------

### Create Organization API Key

Source: https://context7.com/fosrl/pangolin/llms.txt

Generate a new API key for programmatic access to your organization. The full API key is only provided upon creation; store it securely. Subsequent requests use the 'Authorization: Bearer <apiKey>' header.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/org/my-company/api-key \
  -H "Content-Type: application/json" \
  -d '{"name": "Terraform Integration"}'
```

```bash
curl -H "Authorization: Bearer plaintextkey_save_this_now" \
  https://dash.example.com/api/v1/org/my-company/sites
```

--------------------------------

### Push Database Migrations

Source: https://context7.com/fosrl/pangolin/llms.txt

Applies pending database migrations to the connected database.

```bash
npm run db:push
```

--------------------------------

### Attach IDP to Organization with Attribute Mappings

Source: https://context7.com/fosrl/pangolin/llms.txt

Use this endpoint to link an Identity Provider (IDP) to an organization and define role mappings. Ensure the IDP is already created.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/idp/1/org/my-company \
  -H "Content-Type: application/json" \
  -d '{
    "roleMapping": {"pangolin-admins": "Admin", "pangolin-devops": "DevOps"},
    "autoProvision": true
  }'
```

--------------------------------

### Configure Resource Authentication - SSO

Source: https://context7.com/fosrl/pangolin/llms.txt

Enables Single Sign-On (SSO) for a resource using Pangolin session authentication. Assigns specified role IDs to the user.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/resource/42/roles \
  -H "Content-Type: application/json" \
  -d '{"roleIds": [1, 2]}'
```

--------------------------------

### Visitor Authentication - Email Whitelist

Source: https://context7.com/fosrl/pangolin/llms.txt

Allows end-users to authenticate to a protected resource via email whitelist, which sends an OTP email. This endpoint is unauthenticated and rate-limited.

```bash
curl -X POST https://dash.example.com/api/v1/auth/resource/42/whitelist \
  -H "Content-Type: application/json" \
  -d '{"email": "trusted@partner.com"}'
```

--------------------------------

### PUT /api/v1/org/:orgId/site — Create Site

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new site within an organization, supporting different types like 'newt', 'wireguard', and 'local'. For 'newt' type, it returns Newt connector credentials.

```APIDOC
## PUT /api/v1/org/:orgId/site

### Description
Creates a new site (network gateway) within a specified organization. It supports three types: `newt` (recommended, uses NAT traversal via Newt agent), `wireguard` (for raw WireGuard peering), and `local` (for same-host resources). For the `newt` type, the response includes a `newtId` and `secret` required for the Newt connector.

### Method
PUT

### Endpoint
/api/v1/org/:orgId/site

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The ID of the organization to create the site in.

### Request Body
- **name** (string) - Required - The name of the site.
- **type** (string) - Required - The type of site to create. Must be one of: `newt`, `wireguard`, `local`.
- **exitNodeId** (integer) - Optional - Required for `wireguard` type. The ID of the exit node.
- **subnet** (string) - Optional - Required for `wireguard` type. The subnet for the WireGuard peering (e.g., "10.20.1.0/24").
- **pubKey** (string) - Optional - Required for `wireguard` type. The Base64 encoded WireGuard public key.

### Response
#### Success Response (201 Created)
- **data** (object) - Contains the details of the newly created site.
  - **siteId** (integer) - The unique ID of the site.
  - **niceId** (string) - A human-readable ID for the site.
  - **name** (string) - The name of the site.
  - **type** (string) - The type of the site.
  - **newtId** (string) - Optional - The Newt connector ID, provided if `type` is `newt`.
  - **secret** (string) - Optional - The Newt connector secret, provided if `type` is `newt`.
```

--------------------------------

### Create Raw TCP Resource

Source: https://context7.com/fosrl/pangolin/llms.txt

Use this endpoint to create a new raw TCP resource. It requires a JSON payload with resource details such as name, protocol, and proxy port.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/org/my-company/resource \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SSH Bastion",
    "http": false,
    "protocol": "tcp",
    "proxyPort": 2222
  }'
```

--------------------------------

### Use Resource Access Token

Source: https://context7.com/fosrl/pangolin/llms.txt

Authenticates directly to a resource using a generated access token. This endpoint is for direct service-to-service communication.

```bash
curl -X POST https://dash.example.com/api/v1/auth/access-token \
  -H "Content-Type: application/json" \
  -d '{"accessToken": "full_token_value"}'
```

--------------------------------

### Server Information

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieves information about the server, including its version, build type, and enabled feature flags.

```APIDOC
## GET /api/v1/server-info

### Description
Fetches general information about the Pangolin server, such as its version, build type, and feature flags.

### Method
GET

### Endpoint
/api/v1/server-info

### Response
#### Success Response (200)
- **version** (string) - The server version.
- **build** (string) - The build type (e.g., 'oss').
- **flags** (object) - An object containing feature flags.
  - **emailEnabled** (boolean) - Indicates if email features are enabled.
  - **signupWithoutInviteDisabled** (boolean) - Indicates if signup without an invite is disabled.

### Response Example
```json
{
  "data": {
    "version": "1.18.0",
    "build": "oss",
    "flags": {
      "emailEnabled": false,
      "signupWithoutInviteDisabled": true
    }
  }
}
```
```

--------------------------------

### User Registration

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new internal user account. Rate-limited. Requires an invite token if the signup flag is enabled.

```APIDOC
## PUT /api/v1/auth/signup — User Registration

### Description
Creates a new internal user account. Rate-limited to 15 per 15 minutes. Blocked if `disable_signup_without_invite` flag is true (invite token required via `/invite/accept`).

### Method
PUT

### Endpoint
/api/v1/auth/signup

### Request Body
- **email** (string) - Required - The new user's email address.
- **password** (string) - Required - The new user's password.
- **inviteToken** (string) - Optional - The token required for signup if enforced.

### Request Example
```json
{
  "email": "newuser@example.com",
  "password": "StrongPass123!",
  "inviteToken": "abc123-token"
}
```

### Response
#### Success Response (201)
- **data** (null) - Always null on success.
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A message confirming user creation.
```

--------------------------------

### Create Organization Role via API

Source: https://context7.com/fosrl/pangolin/llms.txt

Create a new role within an organization by specifying its name and description. The response includes the new role's ID.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/org/my-company/role \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DevOps",
    "description": "DevOps team members"
  }'
```

--------------------------------

### Create OIDC Identity Provider via API

Source: https://context7.com/fosrl/pangolin/llms.txt

Register an external OpenID Connect provider for Single Sign-On (SSO). This requires details such as client ID, secret, and endpoint URLs.

```bash
curl -b cookies.txt -X PUT https://dash.example.com/api/v1/idp/oidc \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Keycloak",
    "clientId": "pangolin",
    "clientSecret": "oidc_client_secret",
    "authorizationEndpoint": "https://keycloak.example.com/realms/corp/protocol/openid-connect/auth",
    "tokenEndpoint": "https://keycloak.example.com/realms/corp/protocol/openid-connect/token",
    "userInfoEndpoint": "https://keycloak.example.com/realms/corp/protocol/openid-connect/userinfo",
    "scopes": ["openid", "profile", "email"]
  }'
```

--------------------------------

### Complete authentication

Source: https://context7.com/fosrl/pangolin/llms.txt

Completes the security key authentication process by verifying the authentication response.

```APIDOC
## POST /api/v1/auth/security-key/authenticate/verify

### Description
Verifies the security key authentication response to complete the login process.

### Method
POST

### Endpoint
/api/v1/auth/security-key/authenticate/verify

### Request Body
- **WebAuthn AuthenticationResponseJSON** (string) - Required - The signed authentication response from the browser.
```

--------------------------------

### Generate Database Migrations

Source: https://context7.com/fosrl/pangolin/llms.txt

Regenerates migration files based on the current database schema.

```bash
npm run db:generate
```

--------------------------------

### Register Newt Connector

Source: https://context7.com/fosrl/pangolin/llms.txt

Register a Newt connector agent with the provisioning key obtained during site creation. This returns a WireGuard config and a session token.

```bash
# Newt agent calls this on startup with the provisioning key from site creation
curl -X POST https://dash.example.com/api/v1/auth/newt/register \
  -H "Content-Type: application/json" \
  -d '{"provisioningKey": "newtid.secret"}'
# Returns a WireGuard config and Newt session token
```

--------------------------------

### Resource Authentication Methods

Source: https://context7.com/fosrl/pangolin/llms.txt

Configures how visitors authenticate to an HTTP resource.

```APIDOC
## POST /api/v1/resource/:resourceId/password

### Description
Sets a simple password for resource authentication.

### Method
POST

### Endpoint
https://dash.example.com/api/v1/resource/:resourceId/password

### Parameters
#### Path Parameters
- **resourceId** (string) - Required - The ID of the resource.

### Request Body
- **password** (string) - Required - The password for authentication.

### Response
#### Success Response
(No specific success response details provided in source)
```

```APIDOC
## POST /api/v1/resource/:resourceId/pincode

### Description
Sets a 6-digit pincode for resource authentication.

### Method
POST

### Endpoint
https://dash.example.com/api/v1/resource/:resourceId/pincode

### Parameters
#### Path Parameters
- **resourceId** (string) - Required - The ID of the resource.

### Request Body
- **pincode** (integer) - Required - The 6-digit pincode for authentication.

### Response
#### Success Response
(No specific success response details provided in source)
```

```APIDOC
## POST /api/v1/resource/:resourceId/header-auth

### Description
Configures header-based authentication, passing a header to the upstream.

### Method
POST

### Endpoint
https://dash.example.com/api/v1/resource/:resourceId/header-auth

### Parameters
#### Path Parameters
- **resourceId** (string) - Required - The ID of the resource.

### Request Body
- **headerName** (string) - Required - The name of the header.
- **headerValue** (string) - Required - The value of the header.

### Response
#### Success Response
(No specific success response details provided in source)
```

```APIDOC
## POST /api/v1/resource/:resourceId/whitelist

### Description
Enables email whitelist with OTP for resource authentication.

### Method
POST

### Endpoint
https://dash.example.com/api/v1/resource/:resourceId/whitelist

### Parameters
#### Path Parameters
- **resourceId** (string) - Required - The ID of the resource.

### Request Body
- **enabled** (boolean) - Required - Whether the whitelist is enabled.

### Response
#### Success Response
(No specific success response details provided in source)
```

```APIDOC
## POST /api/v1/resource/:resourceId/whitelist/add

### Description
Adds an email to the resource's whitelist.

### Method
POST

### Endpoint
https://dash.example.com/api/v1/resource/:resourceId/whitelist/add

### Parameters
#### Path Parameters
- **resourceId** (string) - Required - The ID of the resource.

### Request Body
- **email** (string) - Required - The email address to add to the whitelist.

### Response
#### Success Response
(No specific success response details provided in source)
```

```APIDOC
## POST /api/v1/resource/:resourceId/roles

### Description
Enables SSO (Pangolin session authentication) by assigning roles to the resource.

### Method
POST

### Endpoint
https://dash.example.com/api/v1/resource/:resourceId/roles

### Parameters
#### Path Parameters
- **resourceId** (string) - Required - The ID of the resource.

### Request Body
- **roleIds** (array of integers) - Required - The IDs of the roles to assign.

### Response
#### Success Response
(No specific success response details provided in source)
```

--------------------------------

### Create Raw TCP Resource

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new raw TCP resource.

```APIDOC
## PUT /api/v1/org/my-company/resource

### Description
Creates a new raw TCP resource.

### Method
PUT

### Endpoint
https://dash.example.com/api/v1/org/my-company/resource

### Request Body
- **name** (string) - Required - The name of the resource.
- **http** (boolean) - Required - Indicates if the resource is HTTP.
- **protocol** (string) - Required - The protocol used (e.g., "tcp").
- **proxyPort** (integer) - Optional - The proxy port for the TCP resource.

### Request Example
```json
{
  "name": "SSH Bastion",
  "http": false,
  "protocol": "tcp",
  "proxyPort": 2222
}
```

### Response
#### Success Response (201 Created)
Returns a Resource object with resourceId, fullDomain, etc.
```

--------------------------------

### Configure Resource Authentication - Pincode

Source: https://context7.com/fosrl/pangolin/llms.txt

Sets a 6-digit pincode for resource authentication. This is a POST request to the resource's pincode endpoint.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/resource/42/pincode \
  -H "Content-Type: application/json" \
  -d '{"pincode": 123456}'
```

--------------------------------

### Retrieve DNS Records for Domain Verification

Source: https://context7.com/fosrl/pangolin/llms.txt

Fetch the required DNS records for a specific domain to complete the verification process.

```bash
curl -b cookies.txt \
  https://dash.example.com/api/v1/org/my-company/domain/dom_xyz/dns-records
```

--------------------------------

### List Sites

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieves a list of all sites within an organization. Returns an array of site objects with their status and type.

```bash
curl -b cookies.txt https://dash.example.com/api/v1/org/my-company/sites
```

--------------------------------

### set-admin-credentials

Source: https://context7.com/fosrl/pangolin/llms.txt

Sets the email and password for the server's administrative account. This command is intended to be run within the Pangolin container.

```APIDOC
## `pangctl` set-admin-credentials

### Description
Sets the credentials for the server's administrative account. This command is typically executed inside the Pangolin container.

### Usage
```bash
node dist/cli.mjs set-admin-credentials --email <admin_email> --password <admin_password>
```

### Parameters
- **--email** (string) - Required - The email address for the admin account.
- **--password** (string) - Required - The password for the admin account.

### Example
```bash
# Inside the container:
node dist/cli.mjs set-admin-credentials \
  --email admin@example.com \
  --password "StrongAdminPass123!"
```

### Output
```
Admin credentials updated successfully
```
```

--------------------------------

### Complete registration with browser-signed credential

Source: https://context7.com/fosrl/pangolin/llms.txt

Completes the registration process by verifying a browser-signed credential.

```APIDOC
## POST /api/v1/auth/security-key/register/verify

### Description
Completes the registration process using a browser-signed credential.

### Method
POST

### Endpoint
/api/v1/auth/security-key/register/verify

### Request Body
- **WebAuthn RegistrationResponseJSON** (string) - Required - The signed registration response from the browser.
```

--------------------------------

### Update Site

Source: https://context7.com/fosrl/pangolin/llms.txt

Updates an existing site's configuration. Accepts a site ID and a JSON payload with fields to modify.

```bash
curl -b cookies.txt -X POST https://dash.example.com/api/v1/site/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Home Lab (Updated)", "dockerSocketEnabled": false}'
```

--------------------------------

### Pangolin Application Configuration

Source: https://context7.com/fosrl/pangolin/llms.txt

This YAML file configures the main application settings for Pangolin, including network ports, logging, telemetry, and security parameters. Ensure sensitive fields like the server secret are changed before deployment.

```yaml
# config/config.yml — full annotated example
gerbil:
  start_port: 51820           # WireGuard base UDP port on the Gerbil container
  base_endpoint: "vpn.example.com"

app:
  dashboard_url: "https://dash.example.com"
  log_level: "info"            # debug | info | warn | error
  log_failed_attempts: false   # Log failed logins to the server log
  telemetry:
    anonymous_usage: true      # Send anonymized usage pings
  notifications:
    product_updates: true
    new_releases: true

domains:
  primary:
    base_domain: "example.com"

server:
  external_port: 3000          # Port exposed to the internet (Traefik upstream)
  internal_port: 3001          # Port used by Gerbil / Badger for internal calls
  next_port: 3002              # Port Next.js listens on
  secret: "CHANGE_ME_32CHARS+" # Encryption key for sensitive DB fields
  session_cookie_name: "p_session"
  resource_access_token_param: "p_token"
  resource_access_token_headers:
    id: "X-Pangolin-Access-Token-Id"
    token: "X-Pangolin-Access-Token"
  resource_session_request_param: "p_session_request"
  cors:
    origins: ["https://dash.example.com"]
    methods: ["GET", "POST", "PUT", "DELETE", "PATCH"]
    allowed_headers: ["X-CSRF-Token", "Content-Type"]
    credentials: false

email:                         # Optional — enables transactional emails
  smtp_host: "smtp.example.com"
  smtp_port: 587
  smtp_user: "user@example.com"
  smtp_pass: "password"
  no_reply: "noreply@example.com"
  ssl: false
  tls: true

flags:
  require_email_verification: false
  disable_signup_without_invite: true    # Only invited users can register
  disable_user_create_org: false         # Only server admins can create orgs when true
  allow_raw_resources: true              # Allow TCP/UDP (non-HTTP) resources
  disable_local_sites: false
  disable_basic_wireguard_sites: false
  disable_product_help_banners: false
  disable_enterprise_features: false

rate_limits:
  auth:
    window_minutes: 15
    max_requests: 500

```

--------------------------------

### List Resource Access Tokens

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieves a list of all access tokens associated with an organization. Requires the organization ID.

```bash
curl -b cookies.txt https://dash.example.com/api/v1/org/my-company/access-tokens
```

--------------------------------

### PUT /api/v1/org — Create Organization

Source: https://context7.com/fosrl/pangolin/llms.txt

Creates a new organization with default roles and provisions necessary resources like SSH CA key pairs and domains.

```APIDOC
## PUT /api/v1/org

### Description
Creates a new organization. This includes setting up an Admin role, a default Member role, provisioning an SSH CA key pair, and assigning all configured domains to the new organization.

### Method
PUT

### Endpoint
/api/v1/org

### Request Body
- **orgId** (string) - Required - The unique identifier for the organization.
- **name** (string) - Required - The display name of the organization.
- **subnet** (string) - Required - The primary subnet for the organization (e.g., "10.10.0.0/16").
- **utilitySubnet** (string) - Required - The utility subnet for the organization (e.g., "10.11.0.0/24").

### Response
#### Success Response (201 Created)
- **data** (object) - Contains the details of the newly created organization.
  - **orgId** (string) - The organization's ID.
  - **name** (string) - The organization's name.
  - **subnet** (string) - The organization's subnet.
  - **utilitySubnet** (string) - The organization's utility subnet.
  - **createdAt** (string) - The timestamp when the organization was created.
```

--------------------------------

### API Key Permissions

Source: https://context7.com/fosrl/pangolin/llms.txt

Manage permissions for API keys, including listing available actions and setting specific permissions.

```APIDOC
## API Key Permissions

### List Actions Available to an API Key

#### Method
GET

#### Endpoint
/api/v1/org/:orgId/api-key/:apiKeyId/actions

### Set Permissions on a Key

#### Method
POST

#### Endpoint
/api/v1/org/:orgId/api-key/:apiKeyId/actions

#### Request Body
- **actionIds** (array of strings) - Required - A list of action IDs to assign to the API key.
```

--------------------------------

### User Login API Endpoint

Source: https://context7.com/fosrl/pangolin/llms.txt

Authenticates an internal user with email and password, supporting TOTP 2FA. Returns a session cookie on success. Rate-limited.

```bash
# Step 1: initial login (no 2FA)
curl -c cookies.txt -X POST https://dash.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "SecurePass123!"}'
# 200 OK → {"data": null, "success": true, "message": "Logged in successfully"}

# Step 2: login with 2FA — first call returns codeRequested: true
curl -c cookies.txt -X POST https://dash.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "SecurePass123!"}'
# 202 → {"data": {"codeRequested": true}, "success": true}

# Step 3: submit TOTP code
curl -c cookies.txt -X POST https://dash.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "SecurePass123!", "code": "123456"}'
# 200 OK → session cookie set

# Logout
curl -b cookies.txt -X POST https://dash.example.com/api/v1/auth/logout

```

--------------------------------

### POST /api/v1/invite/accept — Accept Invitation

Source: https://context7.com/fosrl/pangolin/llms.txt

Accepts an invitation to join an organization by providing the invitation token, email, and a new password.

```APIDOC
## POST /api/v1/invite/accept

### Description
Accepts an invitation to join an organization.

### Method
POST

### Endpoint
/api/v1/invite/accept

### Request Body
- **token** (string) - Required - The invitation token.
- **email** (string) - Required - The email address of the invitee.
- **password** (string) - Required - The new password for the user.

### Request Example
```json
{
  "token": "abc123-xyz",
  "email": "colleague@example.com",
  "password": "NewUserPass123!"
}
```
```

--------------------------------

### Docker Compose Deployment Stack

Source: https://context7.com/fosrl/pangolin/llms.txt

This Docker Compose file defines the production stack, including Pangolin, Gerbil, and Traefik containers. Gerbil shares a network namespace with Traefik for port coexistence.

```yaml
```yaml

```

--------------------------------

### POST /api/v1/auth/device-web-auth/verify — Verify Device Web Auth

Source: https://context7.com/fosrl/pangolin/llms.txt

Verifies the device-based web authentication using the provided code after user approval.

```APIDOC
## POST /api/v1/auth/device-web-auth/verify

### Description
Verifies the device-based web authentication. This endpoint is called after the user has approved the authentication request in their browser.

### Method
POST

### Endpoint
/api/v1/auth/device-web-auth/verify

### Request Body
- **code** (string) - Required - The short-lived code obtained from the `/start` endpoint.
```

--------------------------------

### List Organization Users via API

Source: https://context7.com/fosrl/pangolin/llms.txt

Retrieve a paginated list of users within a specific organization. Ensure you have the necessary cookies for authentication.

```bash
curl -b cookies.txt "https://dash.example.com/api/v1/org/my-company/users?page=1&limit=50"
```