> Markdown version of https://authpi.com/docs/concepts/overview/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Introduction to AuthPI's Core Concepts

Understand the key concepts of AuthPI, including issuers, portals and protocols.

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](/docs/), 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.

<picture align="center">
  <img src="/img/core_concepts_1.png" alt="Diagram of some core concepts of AuthPI" />
</picture>

## 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](/docs/quickstarts/typescript-backend/)** to see them in action.
* Understand how AuthPI's **[Global Identity Mesh](/docs/concepts/architecture)** delivers low-latency authentication and automatic data residency compliance.
* Dive deeper into specific concept pages:
  * [Issuers](/docs/concepts/issuers)
  * [Users](/docs/concepts/users)
  * [Organizations](/docs/concepts/organizations)
  * [Clients](/docs/concepts/clients)
* Explore the **[Core API Reference](/docs/reference/core-api/)** and **[IdP API Reference](/docs/reference/idp-api/)**.