Understanding the core components of AuthPI is key to effectively using the platform to manage identity and access for your applications. This page introduces the fundamental building blocks you’ll work with.

As mentioned in the documentation home, AuthPI has 2 primary APIs:

• Core API: Used for managing and configuring your AuthPI resources.
• IdP API: Used by your applications at runtime for standard authentication flows (OAuth 2.0 / OIDC).

These concepts are the resources you manage via the Core API and that power the interactions via the IdP API.

Issuers: Your Identity Hub

• What it is: An Issuer represents your configurable identity provider instance within AuthPI. Think of it as your central authentication headquarters for a specific purpose or environment (e.g., Production Login, Staging Users).
• Why it matters: It’s where you define how users authenticate, what policies apply, and what the user experience looks like. Each Issuer operates independently regarding its user pool and settings.
• Key Aspects:
  • Holds configuration for allowed authentication methods (password, social login, MFA factors like TOTP/WebAuthn, etc.).
  • Defines user lifecycle policies (signup rules, email verification requirements).
  • Controls UI customization for login, signup, and user portal pages.
  • Manages the list of available scopes (permissions) and OIDC settings.
• Relationships: Belongs to an AuthPI Account. Contains Users and Organizations. Is used by Clients for authentication.
• API Interaction: Primarily configured and managed via the Core API. Its endpoints (like /authorize, /token) are exposed via the IdP API for runtime use.

Users: The Individuals Authenticating

• What it is: A User represents an end-user (a person) who can authenticate through one of your AuthPI Issuers.
• Why it matters: Users are the subjects of authentication. Managing them securely is a primary function of AuthPI.
• Key Aspects:
  • Typically identified by a unique username (often an email address).
  • Has associated authentication factors (password hash, linked social accounts, registered MFA devices).
  • Can have profile information (name, picture, custom attributes) stored as claims.
  • Can be assigned specific scopes (permissions).
  • Can be blocked or deleted.
• Relationships: Belongs to a specific Issuer. Can be a member of one or more Organizations within that Issuer.
• API Interaction: Managed (created, updated, deleted, blocked) via the Core API. Authenticates via the IdP API flows (e.g., by interacting with the /authorize endpoint).

Organizations: Grouping Users (Multi-Tenancy)

• What it is: An Organization is a way to group Users within an Issuer. This is often used for multi-tenancy (representing customer accounts in a SaaS app) or team structures.
• Why it matters: Allows you to manage users collectively, apply group-specific settings or permissions, and facilitate B2B invitation flows.
• Key Aspects:
  • Has members (Users) with specific roles or permissions (represented by scopes within the context of that organization).
  • Can have its own settings (e.g., member limits, invitation rules).
  • Supports inviting new users via email.
  • Can have organization-specific API keys for service accounts or B2B integrations.
• Relationships: Belongs to a specific Issuer. Contains Memberships linking Users to the Organization.
• API Interaction: Managed entirely via the Core API.

Clients: Your Applications

• What it is: A Client represents an application (e.g., a web app, mobile app, backend service) that uses AuthPI for authentication and authorization. It’s the “Relying Party” in OAuth/OIDC terminology.
• Why it matters: Clients are the entities requesting authentication on behalf of users or accessing resources. Registering them allows AuthPI to identify and apply specific rules to each application.
• Key Aspects:
  • Identified by a unique client_id.
  • Often has a client_secret for secure backend communication (confidential clients).
  • Configured with allowed Redirect URIs (where users are sent back after login).
  • Defines which OAuth/OIDC flows it’s allowed to use (e.g., Authorization Code, Refresh Token).
  • Specifies which scopes it is permitted to request.
• Relationships: Belongs to an AuthPI Account. Interacts with a specific Issuer via the IdP API to authenticate Users.
• API Interaction: Registered and managed via the Core API. Interacts at runtime with the IdP API (calling /authorize, /token, etc.).

Events & Webhooks: Monitoring and Reacting

• What they are:
  • Events: Records of significant actions occurring within your AuthPI account and Issuers (e.g., user.created, user.verification.failed, organization.membership.created, client.updated). They form an audit trail.
  • Webhooks: A mechanism to receive notifications about these Events in real-time by having AuthPI send HTTP POST requests to a URL you specify.
• Why they matter:
  • Events: Provide visibility and auditability into identity-related activities.
  • Webhooks: Enable reactive integrations. You can trigger downstream workflows, sync user data to other systems, update analytics, or send custom notifications based on AuthPI events.
• Key Aspects:
  • Events contain details about the action, the subject (User, Org, etc.), the actor (who initiated it), and associated data.
  • Webhooks are configured with a target URL, optional security (signing secret, bearer token), and the specific event types they should subscribe to.
• Relationships: Events are generated based on actions related to other concepts (Users, Clients, etc.). Webhooks listen for specific Event types.
• API Interaction: Events can be queried via the Core API. Webhooks are configured and managed via the Core API.

How They Fit Together (Example Flow)

1. A User attempts to log in to your Client (e.g., your web application).
2. Your Client, configured via the Core API, redirects the User’s browser to the /authorize endpoint of your Issuer on the IdP API.
3. The User authenticates with the Issuer (using methods defined in the Issuer’s config).
4. The Issuer redirects the User back to the Client’s configured Redirect URI with an authorization code.
5. The Client’s backend exchanges the code for tokens by calling the /token endpoint on the IdP API, authenticating itself using its client_id and client_secret.
6. The Issuer validates the code and client credentials, issues tokens (ID, Access, Refresh), and sends them back to the Client.
7. The Client validates the tokens (especially the ID token) and establishes a session for the User.
8. (Meanwhile) The Issuer generates Events like user.verification.succeeded and session.created. If a Webhook is configured for these events, AuthPI sends notifications to your specified URL.

Next Steps

With these core concepts in mind, you’re better equipped to:

• Follow the Quick Start Guide to see them in action.
• Understand how AuthPI’s Global Identity Mesh delivers low-latency authentication and automatic data residency compliance.
• Dive deeper into specific concept pages:
  • Issuers
  • Users
  • Organizations
  • Clients
• Explore the Core API Reference and IdP API Reference.