Authentication

Pidgr uses a passkey-first authentication model. There are no passwords anywhere in the system.

Authentication Methods

Method	Use Case	Priority
Passkeys (WebAuthn/FIDO2)	Primary auth for all users	Default
Email OTP	Enrollment, recovery, fallback	Secondary
SSO/SAML	Enterprise identity federation	Optional
API Keys	Programmatic access (MCP, integrations)	Service-only

Passkeys

Passkeys are the primary authentication method for both the mobile app and admin dashboard. They use the WebAuthn/FIDO2 standard and are backed by your device’s biometric authentication (fingerprint or face recognition).

How It Works

1. User enters their email address
2. Pidgr checks if the user has a registered passkey
3. If a passkey exists, a WebAuthn challenge is returned
4. The device signs the challenge using the stored credential
5. The server verifies the signature and issues JWT tokens

Registering a Passkey

New users register a passkey during their first sign-in:

1. Sign in with email OTP (one-time code sent to your email)
2. After authentication, navigate to Profile → Security
3. Tap Register Passkey
4. Confirm with your device’s biometric
5. The passkey is stored in your platform’s credential manager

Cross-Platform Support

Pidgr passkeys work across:

• iOS/iPadOS — Synced across Apple devices
• Android — Synced via your device’s credential manager
• Web — Platform authenticators or security keys

Email OTP

Email OTP is used as a fallback when passkeys are unavailable:

• First-time sign-in (before passkey registration)
• New device without synced credentials
• Recovery scenarios

The OTP flow sends a 6-digit code to the user’s email. Codes expire after 3 minutes.

SSO/SAML

Enterprise customers can configure SSO federation through their identity provider.

Supported Providers

Pidgr supports any SAML 2.0 identity provider, including Okta, Entra ID, and OneLogin.

Configuration

1. Go to Settings → SSO in the admin dashboard
2. Click Create SSO Provider
3. Enter your IdP’s metadata URL or upload the SAML metadata XML
4. Configure attribute mappings (email, name, department)
5. Verify the domain ownership
6. Enable SSO for your organization

Domain-Based Routing

When a user enters their email, Pidgr checks if the email domain has an SSO provider configured. If so, the user is automatically redirected to the IdP login page.

Attribute Mapping

SSO attribute mappings let you automatically populate user profile fields from SAML assertions:

Pidgr Field	Common SAML Attribute
Email	email, mail
Display Name	displayName, name
Department	department
Job Title	title

Custom attribute mappings can be configured in the admin dashboard under Settings → SSO → Attribute Mappings.

API Keys

API keys provide programmatic access to the Pidgr API for integrations, MCP servers, and automation.

Creating an API Key

1. Go to Settings → API Keys in the admin dashboard
2. Click Create API Key
3. Enter a descriptive name
4. The key is displayed once — copy and store it securely

Key Scoping

API keys inherit permissions from the organization’s role system. Keys are scoped to the organization and cannot access other organizations’ data.

Using API Keys

Include the API key in the Authorization header:

Authorization: Bearer pidgr_<key>

API keys work with both gRPC metadata and Connect-Web HTTP headers.

Security Best Practices

• Rotate keys regularly
• Use separate keys for each integration
• Revoke unused keys promptly
• Never commit keys to source control
• Use environment variables for key storage