port mintlify to fumadocs

This commit is contained in:
miloschwartz
2026-09-25 15:31:51 -04:00
parent dc54fb1017
commit 63199a588c
373 changed files with 13533 additions and 4577 deletions
@@ -0,0 +1,36 @@
---
title: "Device Approvals"
description: "Only allow trusted devices to connect to an organization"
---
<Note>
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
</Note>
By default, any client configured with valid credentials can connect to an organization. To enhance security, you can enable device approvals, which require each new device to be manually approved by an administrator before it can connect.
When device approvals are enabled, the first time a user connects a new device to the organization, the device will be marked as "Pending Approval." An administrator must then review and approve the device in the management console before it can access organization resources.
<Frame>
<img src="/images/device_waiting_approval.png" alt="Device marked pending approval in the Pangolin dashboard" />
</Frame>
All approvals can also be managed from a central page as they stream in to allow admins to approve or deny devices quickly.
<Frame>
<img src="/images/approvals_page.png" alt="Approvals page listing pending devices in the Pangolin dashboard" />
</Frame>
## Enabling Device Approvals
Device approvals are enabled on a per-role basis. To enable device approvals for a role, follow these steps:
1. Click on the **Roles** tab.
2. Select the role you want to enable device approvals for.
3. Toggle the **Require Device Approval** option to enable it.
4. Save your changes.
Once enabled, any new user connecting with that role will require approval from an administrator before it can access organization resources.
<Tip>
You cannot enable device approvals for the "Admin" role.
</Tip>
@@ -0,0 +1,21 @@
---
title: "Change Password"
description: "Change or reset your Pangolin account password"
---
### Change Password
If you're already logged in, you can change your password by clicking your profile menu (top right) and selecting Change Password. You will be required to confirm your old password and enter a new password.
<Tip>
If you want to require password changes at regular intervals for better security, check out the [password rotation documentation](/manage/access-control/password-rotation).
</Tip>
### Reset Password
If you forgot your password, you can use the reset password function. On the login page, select Forgot your password?. This will ask for your username or email. A reset code will be sent to that email to complete the reset.
If you're self‑hosting Pangolin, you will need an SMTP server configured to send emails. If you don't have one configured, the server will log the reset code to the server logs for you to retrieve and use to reset the password.
### Force Reset Server Admin Password
For self‑hosted Pangolin, if you need to force reset your server admin account password server‑side, you can use the internal CLI. [See more here](/self-host/advanced/container-cli-tool).
@@ -0,0 +1,46 @@
---
title: "Users and Roles"
description: "Add internal or external users to your organization and manage roles"
---
## Users in Organizations
Users can be added to organizations. When a user is added to Pangolin, there is a global user object and an organization‑specific user object that links that user to the organization. This allows a user to exist in one or more organizations.
<Tip>
Because the global user exists and a per‑organization user exists, a user invited to an organization may be able to create a new organization. You can disable this functionality via a flag in the config file in self‑hosted Pangolin. [Check out the config file documentation](/self-host/advanced/config-file#feature-flags).
</Tip>
When removing a user from an organization, their account still exists. To completely delete their account, visit the server admin panel as the server admin and delete the global user in the users table.
<Frame>
<img src="/images/users-table.png" alt="Users table in the Pangolin dashboard"/>
</Frame>
### Internal Users
An internal user is an identity managed by Pangolin only. When adding the user, you will receive an invite link. The user needs to use this link to either accept the invite, or create an account for the first time and accept the invite.
### External Users
An external user is an identity managed by an external identity provider. When creating an external user, you will need to select an existing identity provider added to Pangolin. [Check out the documentation on adding an IDP](/manage/identity-providers/add-an-idp).
An identity provider may have auto‑provisioning enabled. This means new users who log in with the IDP are automatically created and you do not need to manually create the user. [Check out the auto‑provisioning documentation](/manage/identity-providers/auto-provisioning).
Even if auto‑provisioning is enabled, you can still manually create users.
## Roles
Roles are how you group users in an organization. A user can belong to more than one role, for example Member, Admin, Contractor, Operations, or any custom roles you define. You use roles with RBAC on resources so access follows those groups: only Operations might reach production resources, while only Contractors might reach test environments, and so on.
On each resource, you define which roles are allowed to access it. A user’s effective access is the union of all resources their roles can reach: they can use any resource that at least one of their assigned roles is permitted to access.
You can create as many custom roles as you need in Pangolin. Each role has a name and a description. The name is the display label and also acts as the unique identifier, so two roles cannot share the exact same name.
To change which roles a user has, open that user’s settings and select the roles they should belong to.
To see how to configure SSH access on a role see [SSH Access](/manage/ssh#configuring-role-permissions).
<Note>
Assigning more than one role to a user is only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) or self-hosted [Enterprise Edition](/self-host/enterprise-edition). In other editions, only one role per user is supported.
</Note>
@@ -0,0 +1,64 @@
---
title: "Forwarded Headers"
description: "Learn how Pangolin forwards user identity information to your backend applications through HTTP headers"
---
Pangolin can forward user identity information to your backend applications through custom HTTP headers. This allows your applications to receive user details directly from the request headers, enabling integration with Pangolin's authentication system. [AI Gateway](/manage/ai/overview) resources send the same headers to the upstream provider when the caller is a known user. See [Identity Headers](/manage/ai/providers/configuration#identity-headers).
<Info>
Forwarded headers are only available when using authentication methods that provide user identity information.
</Info>
## Supported Headers
Pangolin forwards the following headers to your backend when user identity is available:
| Header | Description | Example |
|--------|-------------|---------|
| `Remote-User` | Unique username or user ID | `user_123` |
| `Remote-Email` | User's email address | `john.doe@example.com` |
| `Remote-Name` | User's full name | `John Doe` |
| `Remote-Role` | User's role or group membership | `admin` |
## Authentication Methods
### Headers Available
These authentication methods provide user identity information and will include the forwarded headers:
<CardGroup cols={2}>
<Card title="Single Sign-On (SSO)" icon="users">
Full user identity information including username, email, and name.
</Card>
<Card title="Email-based One Time Passcode (OTP)" icon="envelope">
Only `Remote-Email` is provided, set to the whitelisted address the visitor authenticated with. `Remote-User`, `Remote-Name`, and `Remote-Role` are not available since there is no associated user account.
</Card>
<Card title="Shareable Links" icon="link">
Only available if the link was created with an associated user account. In that case, full user identity information is forwarded, the same as SSO. Links created without an associated user do not provide identity headers.
</Card>
</CardGroup>
### Headers Not Available
These authentication methods do not provide user identity information:
<CardGroup cols={2}>
<Card title="PIN Code" icon="hashtag">
No user identity - only access control.
</Card>
<Card title="Password" icon="lock">
No user identity - only access control.
</Card>
</CardGroup>
## AI Gateway
[AI Gateway](/manage/ai/overview) resources forward the same `Remote-User`, `Remote-Email`, `Remote-Name`, and `Remote-Role` headers to the upstream model API when Pangolin knows the user:
- A public resource called with an [identity key](/manage/ai/virtual-api-keys#identity-keys)
- A public resource called with a [manual key](/manage/ai/virtual-api-keys#manual-keys) attributed to a user
- A private AI Gateway resource called from a connected [Pangolin client](/manage/clients/install-client)
An unattributed manual key authenticates without sending these headers. Details are in [Identity Headers](/manage/ai/providers/configuration#identity-headers).
@@ -0,0 +1,92 @@
---
title: "Shareable Links"
description: "Create Links and use access tokens for browser or programmatic access."
---
Links are special URLs that grant access to one resource without requiring the recipient to sign in as a Pangolin user. Anyone with a web browser on the internet can access the resource if they have a valid Link.
When you create a Link, Pangolin gives you two ways to use it:
- **Link**: This is a Pangolin-hosted URL that validates the validity of the Link and then redirects them to the resource.
- **Access Token Usage**: Use this only when making direct requests to the resource URL from scripts, tools, or integrations.
## Create a Link
From the resource authentication flow, create a Link by:
1. Choosing the target resource.
2. Adding a title if you want the link to be easy to identify later.
3. Setting an expiration, or enabling **Never expire** if the link should stay valid until you revoke it.
4. Copying the generated link or access-token details immediately after creation.
<Frame>
<img src="/images/links-create-modal.png" alt="Create a Link modal" />
</Frame>
<Warning>
Anyone with the Link or access token can use it. Treat both like credentials.
</Warning>
## Use the Access Token
Pangolin can accept a Link access token in either the query string or request headers.
If you are sending access to a person, use the copied **Link** shown at the top of the modal.
Use **Access Token Usage** only when you are calling the resource URL directly on each request.
This is why the two URLs often look different:
- The **Link** is usually on your Pangolin domain.
- The **Access Token Usage** examples use the resource URL directly.
<Frame>
<img src="/images/links-access-token-usage.png" alt="Access token usage examples for a shareable link" />
</Frame>
### Query Parameter
Pangolin accepts the access token in the `p_token` query parameter:
```bash
curl "https://resource.example.com/?p_token=<token-id>.<access-token>"
```
The query-string value is the token ID and token joined with a `.`.
Some deployments may use a different query parameter name.
The query parameter must be sent in every request to the resource, not just the first time.
### Request Headers
By default, Pangolin accepts these headers:
- `P-Access-Token-Id`
- `P-Access-Token`
Example:
```bash
curl \
-H "P-Access-Token-Id: <token-id>" \
-H "P-Access-Token: <access-token>" \
"https://resource.example.com/"
```
This is the same token data as the query-string form, split into two headers instead of `<token-id>.<access-token>`.
Some deployments may use different header names.
The headers must be sent in every request to the resource, not just the first time.
## Expiration and Revocation
- Expiring links stop working automatically when their lifetime ends.
- Non-expiring links remain valid until you delete them.
- Deleting the Link revokes both the Link and its access token.
## Important Notes
- Links are best for targeted sharing and automation, not broad long-term access.
- Link-based access does not carry per-user identity headers to the upstream app. For identity-aware upstream integrations, see [Forwarded Headers](/manage/access-control/forwarded-headers).
@@ -0,0 +1,40 @@
---
title: "Custom Login Page"
description: "Configure a custom authentication page URL for your organization"
---
<Note>
Custom auth pages are only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup).
</Note>
Custom organization authentication pages let you serve the login page at your own domain instead of the default `app.pangolin.net`. This provides better user experience and brand consistency.
## Benefits
**For Resource Authentication:**
- Users are redirected to your custom domain for login
- Familiar domain builds trust and security awareness
- Consistent branding throughout the authentication flow
**For Identity Provider Integration:**
- Centralized login page for your organization
- Choose between multiple login methods (Google, Azure, etc.)
- Platform SSO: login once, access all Pangolin resources
- Direct access to the Pangolin management dashboard
<Frame>
<img src="/images/org-auth-page.png" alt="Organization login page with multiple login methods" />
</Frame>
## Configuration
1. Go to **Settings** in your organization sidebar
2. Use the domain picker to select your custom domain
3. Save your changes
<Note>
You need to add a custom domain to your organization first. Free domains (`*.tunneled.to`, `*.hostlocal.app`, etc.) cannot be used for auth pages. [Learn how to add domains](/manage/domains)
</Note>
<Frame>
<img src="/images/set-org-auth-page-domain.png" alt="Domain picker for the auth page in Pangolin settings" />
</Frame>
@@ -0,0 +1,29 @@
---
title: "Multi-Factor Authentication"
description: "Enable and manage two-factor authentication and enforcement for your organization"
---
Pangolin supports two‑factor authentication (2FA) for Pangolin user accounts.
### Enable or Disable 2FA
- Click your profile menu (top right) to enable two‑factor authentication.
- You will need to confirm your password and code before enabling/disabling 2FA.
### Supported Methods
- **Time‑based one‑time code (TOTP)**: Use an authenticator app (e.g., 1Password, Google Authenticator).
- **Push via email**: Contact sales to enable.
- **Push via Duo**: Contact sales to enable.
### Enforcement
<Note>
Two‑factor enforcement (requiring 2FA at login) is available in [Enterprise Edition](/self-host/enterprise-edition) only.
</Note>
To enable enforcement, go to Organization Settings and toggle 2FA enforcement in the Security section.
- Enforcement is configured per organization.
- MFA enforcement only applies to internal Pangolin user accounts. This policy does not apply to accounts linked to an external identity provider.
- When enforced, users must enable 2FA before accessing the organization or its resources.
- Users without 2FA will see a prompt directing them to enable it before proceeding.
@@ -0,0 +1,17 @@
---
title: "Password Rotation"
description: "Configure password expiration and rotation requirements for your organization"
---
By default, Pangolin does not require passwords to be rotated on a regular basis. However, password rotation can be required on a per‑organization basis.
### Configuration
<Note>
Password expiry and rotation is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
</Note>
To enable password rotation, go to Organization Settings and select a maximum password age in the Security section. After the configured period expires, users will be prompted to change their password when accessing the organization or its resources.
- Password rotation is enforced on a per‑organization basis.
- Password rotation only applies to internal Pangolin user accounts. This policy does not apply to accounts linked to an external identity provider.
- Users who need to change their password will see a prompt directing them to update it before proceeding.
@@ -0,0 +1,108 @@
---
title: "Rules"
description: "Configure rules to allow or deny access to resources without authentication"
---
Rules allow you to either "allow" and bypass the Pangolin auth system (no pin, login, password), or "deny" and fully reject the request. After you create a resource you can select the "Rules" tab on the sidebar and enable rules. On public resources, you can also define rules in a [resource policy](/manage/resources/public/resource-policies) and share them across multiple resources.
<CardGroup cols={3}>
<Card title="Bypass Auth" icon="check">
Bypass authentication completely for matching requests. Users can access resources without any login or PIN.
</Card>
<Card title="Block Access" icon="x">
Completely reject requests that match the rule. Useful for blocking admin paths or sensitive endpoints.
</Card>
<Card title="Pass to Auth" icon="x">
Pass requests that match the rule to the next stage for user to authenticate with SSO, password, or pin. Useful for enforcing auth on specific paths while allowing others.
</Card>
</CardGroup>
## Types of Rules
Rules are processed from top to bottom in order of their priority. This means you can have multiple rules to bypass auth and to just flat deny users at the end.
Right now you can match on the following items:
### Path
Path match rules allow URL patterns defined with plain text and wildcards (`*`) that match any characters. Patterns and URLs are split into segments (using `/`), and **each segment is matched individually**.
#### Examples:
- `blog/posts`
Matches the exact path `/blog/posts`.
- `blog/*`
Matches any path under `/blog` (e.g., `/blog/travel`).
- `*/2023/*`
Matches paths with `/2023/` as a middle segment (e.g., `/news/2023/summary`).
- `article*`
Matches **segments** starting with "article" (e.g., `/article-123`).
- `*admin*`
Matches **segments** containing "admin" (e.g., `/my-admin-panel`).
- `personal-*/*`
Matches paths where the first segment starts with `personal-` and is followed by any segment (e.g., `/personal-blog/post`).
#### Segment-by-Segment Matching
- **Normalization:**
Both patterns and URLs are split into segments. For example, `/blog/journal/entry` becomes `["blog", "journal", "entry"]`, while `/blog*` becomes `["blog*"]`.
- **Validation:**
Each pattern segment must correspond to a URL segment, and wildcards match zero or more characters within that segment. A pattern like `/blog*` only matches the first segment, so URLs with extra segments require additional placeholders (e.g., `/blog*/*`).
### Country
Country match rules allow you to specify allowed or denied countries for requests based on their IP address. This is useful for geo-restrictions or compliance with regional regulations.
We use a IP database to geolocate the IP address but this is not always accurate. Try to keep it updated, but there may be cases where the location is incorrect.
Select the "ALL" option to match all countries for allowing or denying access.
To use country rules, follow this guide to set up the geolocation database: [Enable Geo-location](/self-host/advanced/enable-geolocation).
### Region
Region match rules allow you to specify allowed or denied regions for requests based on their IP address. This is useful for geo-restrictions or compliance with regional regulations. Regions are made up of a list of countries in that region (e.g. "EU" includes France, Germany, etc.) so this is a more broad match than country.
To use region rules, follow this guide to set up the geolocation database: [Enable Geo-location](/self-host/advanced/enable-geolocation).
### CIDR
CIDR (Classless Inter-Domain Routing) notation specifies IP address ranges using an IP address and a network prefix length. The format is [IP address]/[prefix length].
**Examples:**
- `192.168.1.0/0` - Matches all 256 IPs from 192.168.1.0 to 192.168.1.255
- `10.0.0.0/8` - Matches any IP starting with 10 (16.7 million addresses)
- `2001:db8::/32` - Matches a range of IPv6 addresses
- `0.0.0.0/0` - Matches all IPv4 addresses
<Note>
The prefix length (1-32 for IPv4, 1-128 for IPv6) determines how many bits from the left are fixed. Smaller prefix numbers match larger ranges.
</Note>
### IP
Pretty simple: you can match on simply an IP address like your home IP to bypass auth. This is the same as entering a /32 CIDR.
### ASN
ASN (Autonomous System Number) match rules allow you to specify allowed or denied ASNs for requests based on their IP address. This is useful for blocking or allowing traffic from specific ISPs or organizations.
To use ASN rules, follow this guide to set up the ASN lookup database: [Enable ASN Lookup](/self-host/advanced/enable-asn-lookup).
**Examples:**
- `23.234.134.32`
- `34.45.245.64`
- `192.168.1.1`
### Community Contributed Rules
Some common bypass paths for common self hosted apps can be found [in the community contributed rules](/self-host/community-guides/rules).
@@ -0,0 +1,11 @@
---
title: "Security Keys"
description: "Use security keys for passwordless login to your Pangolin account"
---
You can log in with security keys, also known as passwordless login. On the login page, there is an option below the login button to Log in with security key.
### Add a Security Key
To add a security key, you must first be logged in. Then click your profile menu (top right) and select Add Security Keys. Follow the steps to add your key.
Once a security key is added to your account, you can select the Continue with security key option the next time you log in.
@@ -0,0 +1,19 @@
---
title: "Session Length"
description: "Configure maximum session length and expiration policies for your organization"
---
By default, Pangolin keeps extending a session indefinitely if a user is actively using it. If a user is not actively using the session, it will expire after 30 days.
However, you can require users to log in at regular intervals by enforcing maximum session lengths on a per‑organization basis.
### Configuration
<Note>
Session length enforcement is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
</Note>
To enable session length enforcement, go to Organization Settings and set a maximum session length in the Security section. After this amount of time, users will be prompted to log back in to acquire a fresh session.
- Session length enforcement is configured per organization.
- Session length enforcement applies to both internal Pangolin users and users linked to external identity providers.
- Users whose session has expired will see a prompt directing them to log in again before proceeding.