Authentication

Pidgr is fully passwordless. There are no passwords anywhere in the system — and therefore no password resets and no forgot-password flow.

How people sign in

Users sign in at auth.pidgr.com:

1. Enter your work email address.
2. Pidgr emails you a one-time code.
3. Enter the code to complete sign-in.

After signing in, users are encouraged to enroll a passkey so subsequent sign-ins are a single biometric confirmation instead of an email round-trip.

Method	Use case
Email one-time code	Sign-in with nothing but your email — first sign-in, new devices, recovery
Passkeys (WebAuthn/FIDO2)	Fast subsequent sign-ins backed by your device’s biometrics
Enterprise SSO (SAML 2.0 / OIDC)	Federate sign-in through your identity provider

Machine access — integrations, CI, and AI agents — uses scoped API keys or OAuth 2.1 instead.

Passkeys

Passkeys use the WebAuthn/FIDO2 standard and are backed by your device’s biometric authentication (fingerprint or face recognition). The private key never leaves your device’s credential manager.

Enrolling a passkey

1. Sign in with an email one-time code.
2. When prompted (or from Profile → Security), choose Register Passkey.
3. Confirm with your device’s biometric.
4. The passkey is stored in your platform’s credential manager and synced according to your platform’s rules.

Cross-platform support

• iOS/iPadOS — synced across Apple devices
• Android — synced via your device’s credential manager
• Web/Desktop — platform authenticators or hardware security keys

If a device has no synced passkey, you can always fall back to an email one-time code and enroll a new passkey there.

Invitations

Admins add members by inviting them by email (from the admin dashboard, the API, or an invite link). Invited users receive a branded invitation email; the button in that email lands them on the auth.pidgr.com sign-in page, where they sign in with a one-time code sent to the invited address. No account setup form, no credentials to create.

An invitation is scoped to your organization: if the invitee already uses Pidgr with another organization, the same identity gains a membership in yours.

Enterprise SSO

Organizations can federate sign-in through their identity provider. Pidgr supports SAML 2.0 and OIDC providers, including Okta and Microsoft Entra ID.

Configuration

1. Go to Settings → SSO in the admin dashboard.
2. Click Create SSO Provider.
3. Enter your provider’s SAML metadata URL or OIDC discovery URL.
4. Optionally override attribute mappings.
5. Enable the provider for your organization.

Attribute mapping

For identity providers that use non-standard SAML attribute names, you can override which attributes map to the user’s email, first name, and last name. Mappings are configured under Settings → SSO.

Machine access

There are two ways for software to call the Pidgr API. Both are organization-scoped and permission-checked on every request.

Scoped API keys

API keys are the simplest path for server-to-server integrations, scripts, and CI.

• Org-scoped — a key belongs to one organization and can never read another organization’s data. The org is resolved from the key itself; it is never taken from the request.
• Explicit permissions — every key carries an explicit permission list, set at creation time. At least one permission is required, and requests outside the key’s permissions fail with a permission error naming the missing permission.
• Optional expiry — set an expiration time at creation, or leave the key non-expiring and rotate it yourself.

Creating a key

1. Go to Settings → API Keys in the admin dashboard.
2. Click Create API Key, name it, and select the permissions it needs.
3. Optionally set an expiration time.
4. The key (prefix pidgr_k_) is displayed once — copy and store it securely. It cannot be retrieved later.

Using a key

Send the key as a bearer token:

Authorization: Bearer pidgr_k_<key>

This works identically over gRPC metadata and Connect HTTP headers. See the API Integration Tutorial for full examples.

OAuth 2.1

Pidgr runs an OAuth 2.1 authorization server for integrations that act on behalf of a signed-in user — including the Pidgr MCP server and personal CLI tools.

• Authorization code + PKCE — the only interactive grant. PKCE with S256 is mandatory; there is no implicit flow and no password grant (Pidgr has no passwords).
• Scoped tokens — clients request coarse scopes such as campaigns:read or campaigns:write at authorization time, and the user approves them on a consent screen.
• Effective permissions are an intersection — a token can never do more than either its scopes or the approving user’s role allows: effective = token scopes ∩ user's role permissions. Granting a broad scope to a narrow user yields narrow access.
• Refresh tokens — access tokens are short-lived; clients refresh them automatically. Consent can be revoked at any time.
• Standard discovery — endpoints are published at the issuer’s /.well-known/oauth-authorization-server document.

Choose OAuth when the credential should represent a person and follow their role; choose an API key when the credential represents a system with a fixed permission set.

Security best practices

• Rotate API keys regularly, or create them with an expiry
• Use a separate key per integration, scoped to the minimum permissions it needs
• Revoke unused keys promptly
• Never commit keys to source control — use environment variables or a secrets manager
• Prefer OAuth over long-lived keys for anything a person operates interactively