An Issuer is your identity provider within AuthPI. It’s the central configuration hub that controls how users authenticate, what security policies apply, and what the login experience looks like for your application.

Think of an Issuer as your branded authentication service. When users sign up or log in to your application, they interact with your Issuer’s configuration—the authentication methods they see, the signup requirements they must meet, and the branding they experience all come from your Issuer settings.

Key Concepts

One Issuer Per Application (or Environment)

Most customers create one Issuer per application or environment. For example:

• Production Issuer for your live application
• Staging Issuer for testing (with is_test: true)
• Separate Issuers if you have multiple distinct products under the same Account

Each Issuer has its own user pool, authentication configuration, and security policies. Users in one Issuer are completely separate from users in another.

When to use multiple Issuers: If you have genuinely separate products with different user bases, separate Issuers make sense. However, if you want users to have a single identity across multiple applications (single sign-on), use one Issuer with multiple Clients instead.

Issuer URL

Every Issuer has a unique identifier and URL. Your applications use this URL for OAuth 2.0 and OpenID Connect flows:

https://idp.authpi.com/{issuer_id}

You can also configure a custom domain (e.g., auth.yourcompany.com) to white-label the authentication experience. Custom domains are recommended for production applications—they build trust with your users and make your authentication flow feel native to your product rather than a third-party service.

What Issuers Control

Authentication Methods

Issuers define which authentication methods are available to your users. You can enable multiple methods and configure each one independently.

Password Authentication

The traditional email and password combination. Despite the rise of passwordless options, passwords remain familiar to users and work universally across devices and contexts.

When to use: Password authentication is a good default for most applications. Users understand it, and it doesn’t require email delivery infrastructure to work in real-time (unlike magic links or OTPs).

Trade-offs: Passwords can be weak, reused, or phished. If you enable passwords, consider also enabling MFA options like TOTP or WebAuthn to add a second layer of security.

Email Link (Magic Links)

Users receive a link via email that logs them in directly—no password needed. This shifts the security model to “whoever controls this email inbox can log in.”

When to use: Magic links work well for applications where users log in infrequently (weekly or monthly) and might forget passwords. They’re also good for low-friction onboarding where you want to minimize signup barriers.

Trade-offs: Magic links depend on email delivery speed. If your email provider is slow or messages land in spam, users get frustrated. They also don’t work well for users who need to log in frequently throughout the day—checking email every time becomes tedious.

Email OTP

Similar to magic links, but users receive a numeric code to enter instead of clicking a link. This is sometimes perceived as more secure because users manually enter the code rather than clicking a potentially spoofed link.

When to use: Email OTP is useful when you want passwordless authentication but your users are in contexts where clicking email links is inconvenient (e.g., logging in on a different device than where they receive email).

OAuth 2.0 (Social Login)

Let users authenticate with existing accounts from providers like Google, GitHub, or Microsoft. AuthPI handles the OAuth flow and retrieves basic profile information.

When to use: Social login dramatically reduces signup friction—users don’t need to create yet another password. It’s particularly effective for consumer applications and developer tools (GitHub login for dev tools is almost expected). It’s also useful when you want to verify that users have a legitimate account with a trusted provider.

Trade-offs: You become dependent on third-party providers. If Google has an outage, your Google-login users can’t sign in. Consider always offering at least one backup authentication method. Also, some users are privacy-conscious and don’t want to connect their social accounts to every service they use.

Configuration required: For each OAuth provider, you’ll need to register your application with that provider and obtain a Client ID and Client Secret. AuthPI supports major providers including Google, GitHub, Microsoft, Apple, and generic OIDC providers.

WebAuthn (Passkeys and Security Keys)

WebAuthn enables biometric authentication (fingerprint, face recognition) and hardware security keys. This is the most secure option available—credentials are cryptographic and phishing-resistant.

When to use: WebAuthn is excellent for security-conscious applications, enterprise deployments, and as an MFA factor. Passkeys (synced WebAuthn credentials) are increasingly supported across devices and provide both security and convenience.

Trade-offs: Not all users have devices that support WebAuthn, and the user experience can be confusing for those unfamiliar with it. Consider offering WebAuthn as an option alongside passwords rather than requiring it. Also, if a user loses their security key and has no backup authentication method, account recovery becomes difficult.

TOTP (Authenticator Apps)

Time-based one-time passwords generated by apps like Google Authenticator, Authy, or 1Password. TOTP is typically used as a second factor rather than primary authentication.

When to use: TOTP is the most widely supported MFA method. If you need to add two-factor authentication and want maximum compatibility, TOTP works on virtually any device with an authenticator app installed.

Trade-offs: Users need to set up an authenticator app, which adds friction. The codes expire every 30 seconds, which can frustrate users with slow typing. If users lose their phone without backup codes, account recovery is painful.

Backup Codes

One-time recovery codes that users can store safely and use if they lose access to their primary authentication methods.

When to use: Always offer backup codes when you enable MFA. They’re the safety net that prevents permanent account lockout. Generate them during MFA setup and encourage users to store them securely (password manager, printed copy in a safe place).

Combining Authentication Methods

Most production applications combine several methods. A typical secure setup might be:

• Primary: Password + Google OAuth (user’s choice)
• MFA: TOTP or WebAuthn (optional but encouraged)
• Recovery: Backup codes

For a passwordless approach:

• Primary: Email link or WebAuthn
• Recovery: Backup codes + Email OTP

Each method can be enabled for login, signup, or both. For example, you might allow users to sign up with Google OAuth but require them to add a password afterward for account recovery purposes.

Signup Policy

Control who can create accounts and how the registration process works.

Enabling or Disabling Signup

You can disable signup entirely if you want to control account creation through other means (admin invitation, API provisioning, etc.).

When to disable: Enterprise applications often disable self-service signup. Accounts are created by administrators or provisioned through SSO. This ensures only authorized users from known organizations can access the system.

Email Verification

When enabled, users must verify their email address before their account is fully activated. They receive a verification link and can’t complete certain actions until they click it.

When to require: Email verification is recommended for most applications. It confirms that users control the email addresses they claim, which is important for password recovery and communication. It also reduces fake account creation.

When to skip: If you’re building an application where friction must be absolutely minimal (e.g., a quick demo or trial), you might allow unverified accounts initially and prompt for verification later. Be aware this opens the door to abuse.

Admin Approval

New accounts require manual approval from an administrator before activation.

When to use: Approval workflows make sense for exclusive communities, beta programs, or applications where you need to vet users before granting access. For example, a private investment platform might require approval to ensure users meet accreditation requirements.

Trade-offs: Approval creates delays and administrative overhead. Users who sign up and then wait hours or days for approval may lose interest. If you use approval, ensure your team can review requests promptly.

Email Domain Restrictions

You can restrict signups to specific email domains (allowlist) or block certain domains (blocklist).

Allowlist use case: A B2B SaaS company selling to enterprises might restrict their customer’s instance to @customer.com emails only. This ensures only employees of that customer can create accounts.

Blocklist use case: Block known disposable email domains (like mailinator.com or tempmail.com) to reduce fake signups and abuse. AuthPI can also block “untrusted” domains—email providers that don’t support proper verification.

Default Scopes

Scopes are permissions that define what users can do or what data they can access. Default scopes are automatically assigned to every new user.

Typically, you’d grant basic scopes like profile and email by default. More sensitive scopes (like admin or billing) should be assigned explicitly to specific users.

Auto-Create Organization

When enabled, AuthPI automatically creates an Organization for each new user who signs up.

When to use: This is useful for B2B SaaS applications where each customer (company) should have their own organization. The first user from a company signs up, an organization is created for them, and they can then invite their teammates.

When to skip: For consumer applications or simple B2C use cases, organizations add unnecessary complexity. Users are just individuals, not members of teams.

Session Management

Sessions track logged-in users. When a user authenticates successfully, AuthPI creates a session that remains valid until it expires or is explicitly revoked.

Session Lifetime (Max Age)

The maximum duration a session can remain valid, regardless of activity. The default is 30 days.

Shorter sessions (hours to days): More secure because compromised sessions have limited windows of usefulness. Appropriate for sensitive applications like banking or healthcare where you want users to re-authenticate frequently.

Longer sessions (weeks to months): More convenient for users who access your application regularly. Appropriate for consumer apps, productivity tools, or any context where forcing frequent re-authentication would be annoying.

Idle Timeout

Sessions can expire after a period of inactivity, even if the max age hasn’t been reached.

When to use: Idle timeouts are useful for shared devices or kiosk scenarios. If a user walks away from a public computer without logging out, the session expires automatically after a few minutes of inactivity.

Trade-offs: Aggressive idle timeouts frustrate users who step away briefly and return to find themselves logged out. Balance security needs against user experience.

Device Fingerprinting

When enabled, AuthPI tracks device characteristics and can require additional verification if a session is used from a different device than expected.

When to use: Device fingerprinting adds security for sensitive applications. If someone steals a session token and tries to use it from a different device, AuthPI can detect the mismatch and require re-authentication.

Trade-offs: Legitimate users who switch devices frequently (or use privacy tools that mask device fingerprints) may face extra friction.

Security Policies

Refresh Tokens

OAuth flows can issue refresh tokens that allow clients to obtain new access tokens without requiring users to re-authenticate. Refresh tokens typically have longer lifetimes than access tokens.

When to enable: Most applications should enable refresh tokens. They allow seamless background token renewal, so users don’t get unexpectedly logged out when their access token expires.

When to disable: If you’re building a highly sensitive application where you want to force re-authentication at fixed intervals, disable refresh tokens. Users will need to log in again when their access token expires.

Redirect URI Policy

After authentication, AuthPI redirects users back to your application. The redirect URI policy controls which URLs are allowed as redirect targets.

Whitelist mode (recommended for production): Only pre-registered URIs are allowed. This prevents attackers from tricking users into authenticating and then redirecting to malicious sites. You must register each valid redirect URI in advance.

Prefix mode: URIs matching certain prefixes are allowed. This provides some flexibility (e.g., allowing https://app.example.com/*) while still restricting to your domain.

None (development only): Any redirect URI is allowed. This is convenient during development when you’re frequently changing ports or URLs, but it’s a security risk in production.

CORS Origins

Specifies which browser origins can make requests to your Issuer’s authentication endpoints. This is relevant for single-page applications that make authentication requests directly from the browser.

Identity Policy

Username Type

AuthPI supports three username formats:

• Email: Users are identified by email address (most common)
• Phone: Users are identified by phone number (useful for mobile-first apps or regions where phone is more common than email)
• Unique text: Users choose a username (useful for communities, forums, or apps where email privacy is important)

Choose based on how you need to communicate with users and what identifiers make sense for your application.

Domain Restrictions

Similar to signup policy domain restrictions, but applied at the identity level. This ensures that even users created via API (not just self-service signup) must have email addresses from allowed domains.

Branding

Customizing the look and feel of AuthPI’s hosted login pages helps build user trust. When users see your logo, colors, and company name on the login page, they’re more confident they’re in the right place—not being phished.

Display name: The name shown on login pages (e.g., “Acme Corp” rather than a technical issuer ID).

Logo: Your company logo, displayed prominently on authentication pages.

Theme colors: Primary and accent colors that match your brand.

Links: Privacy policy, terms of service, and support page links. These are important for legal compliance and user trust.

Even if you plan to eventually build custom login pages, starting with branded hosted pages gets you to market faster while maintaining a professional appearance.

Portals

AuthPI can host several user-facing pages:

Login portal: Where users sign in. This is the page your application redirects to when authentication is needed.

Signup portal: New user registration. Can be disabled if you’re provisioning accounts through other means.

Password reset portal: Self-service password recovery. Users enter their email, receive a reset link, and set a new password.

User portal: A self-service page where authenticated users can manage their profile, change their password, configure MFA, view active sessions, and manage connected OAuth accounts.

Each portal can be individually enabled or disabled. You can also provide custom URLs if you prefer to build and host these pages yourself—AuthPI will redirect to your custom pages instead of the hosted ones.

API Credentials

AuthPI supports two types of programmatic credentials:

Personal tokens: Issued to individual users for API access. Think of these like GitHub personal access tokens—users can create them to authenticate scripts or integrations acting on their behalf. Unlike a long-lived GitHub PAT, an AuthPI personal token is a signed JWT and stops working after at most 21 days (see JWKS & key rotation).

API keys: Issued to organizations for service-to-service communication. These are used when applications or services need to make API calls that aren’t tied to a specific user.

For each type, you can control:

• Whether they’re enabled at all
• Whether users/members can self-manage (create, revoke) their own credentials
• Maximum number of tokens per user or keys per organization

When to enable personal tokens: If your users need to integrate with your API from scripts, CLI tools, or third-party services, personal tokens provide a secure way to do this without sharing passwords.

When to enable API keys: If you have organizations that need to integrate your service with their own systems (webhooks, automated provisioning, etc.), API keys let them authenticate programmatically.

Relationships to Other Entities

Issuers and Accounts

An Issuer belongs to exactly one Account. Your Account is your billing and administrative entity in AuthPI—it can contain multiple Issuers.

Account (your AuthPI subscription)
├── Issuer (Production)
├── Issuer (Staging)
└── Issuer (Internal Tools)

All Issuers under an Account share the same billing plan and administrative users, but each has independent configuration and user pools.

Issuers and Users

Users exist within a single Issuer. A user in your Production Issuer is completely separate from a user in your Staging Issuer, even if they share the same email address.

This separation is intentional—it means your staging environment has its own test users that don’t affect production, and you can experiment with authentication settings without impacting real users.

Issuers and Organizations

Organizations are groups of users within an Issuer. They’re commonly used for multi-tenancy—each of your customers might be represented as an Organization containing their team members.

Organizations inherit some settings from their parent Issuer but can have their own configuration for things like member limits and API keys.

Issuers and Clients

Clients (your applications) are registered at the Account level but interact with a specific Issuer for authentication. A single Client can potentially work with multiple Issuers, but in practice most Clients are configured for one Issuer.

When a Client initiates an OAuth flow, it targets a particular Issuer’s authorization endpoint. The Issuer’s configuration determines what authentication methods are available, what scopes can be requested, and where users can be redirected after authentication.

Data residency

Every Issuer is provisioned with eight regional identity stores. When a user is created, AuthPI places their identity in a nearby available store and it stays there. Self-service signup follows the user’s request geography. Core API creation follows the API caller’s geography by default, or can require a supported region or the EU jurisdiction. Explicit requirements never fall back to another placement.

There is nothing to enable for automatic placement. For compliance-sensitive API creation, set placement.region or placement.jurisdiction: "eu"; AuthPI rejects the request if no matching store has capacity. Each user’s assigned region is visible in the Core API’s list users response, so you can always show where a given user’s data lives.

Note: Geographic placement covers user identity data. Your own application data (stored in your own systems) remains your responsibility to handle according to relevant regulations.

See Global Identity Mesh for the full region list, the hard versus best-effort distinction, and what data is regional versus global.

Managing Issuers

Issuers are managed through the Core API. Common operations include:

Operation	Endpoint
Create Issuer	POST /accounts/{account_id}/issuers
Get Issuer	GET /accounts/{account_id}/issuers/{issuer_id}
List Issuers	GET /accounts/{account_id}/issuers
Update Issuer	PATCH /accounts/{account_id}/issuers/{issuer_id}
Delete Issuer	DELETE /accounts/{account_id}/issuers/{issuer_id}

Authentication methods have their own endpoints:

Operation	Endpoint
Add Method	POST /accounts/{account_id}/issuers/{issuer_id}/auth-methods
Update Method	PATCH /accounts/{account_id}/issuers/{issuer_id}/auth-methods/{method_id}
Remove Method	DELETE /accounts/{account_id}/issuers/{issuer_id}/auth-methods/{method_id}

You can also manage Issuers through the AuthPI Dashboard, which provides a visual interface for all these operations.

Example Configurations

Consumer SaaS Application

A typical B2C application prioritizing ease of use:

Authentication Methods:

• Password (login and signup)
• Google OAuth (login and signup)
• Apple OAuth (login and signup)

Signup Policy:

• Enabled: Yes
• Email verification: Required
• Domain restrictions: None (open to everyone)
• Auto-create organization: No

Sessions:

• Max age: 30 days
• Idle timeout: None

Security:

• Refresh tokens: Enabled
• Redirect URI policy: Whitelist

This configuration minimizes friction while maintaining reasonable security. Users can sign up quickly with social login or email, and long sessions mean they rarely need to re-authenticate.

B2B SaaS Platform

A business application where each customer is an organization:

Authentication Methods:

• Password (login and signup)
• Google Workspace OAuth (login and signup)
• Microsoft OAuth (login and signup)
• TOTP (optional MFA, encouraged)

Signup Policy:

• Enabled: Yes
• Email verification: Required
• Domain restrictions: Block untrusted email domains
• Auto-create organization: Yes

Sessions:

• Max age: 14 days
• Idle timeout: 4 hours

Security:

• Refresh tokens: Enabled
• Redirect URI policy: Whitelist

This configuration supports business users who primarily use corporate Google or Microsoft accounts. Auto-organization creation means the first user from each company gets an organization, and shorter sessions with idle timeout provide better security for business data.

Enterprise Internal Tool

A sensitive internal application with strict security requirements:

Authentication Methods:

• Password (login only, no self-service signup)
• WebAuthn (required as MFA)
• Backup codes

Signup Policy:

• Enabled: No (accounts created by admins)
• Email verification: Required
• Domain restrictions: Allowlist corporate domain only

Sessions:

• Max age: 8 hours (one work day)
• Idle timeout: 30 minutes
• Device fingerprinting: Enabled

Security:

• Refresh tokens: Disabled
• Redirect URI policy: Whitelist (single URI)

This configuration prioritizes security over convenience. No self-service signup, mandatory MFA with WebAuthn, short sessions, and no refresh tokens ensure tight control over access.

Next Steps

• Create your first Issuer in the Quick Start guide
• Learn about Users and how they authenticate
• Understand Organizations for multi-tenancy
• Register Clients to connect your applications