Connections

In Faable Auth, a Connection represents a source of users. It defines how your users will authenticate when logging into your application. Connections are the core building blocks that enable different authentication methods without having to write custom integrations for each one of them.

You can configure and manage all your connections directly from the Faable Dashboard.

Types of Connections

Every connection has a connection_type. These are all of them:

Those four categories (database, social, passwordless, oidc) are what the dashboard sidebar and the API filter on: GET /connections?category=social.

Enterprise SSO: a company’s Okta, Entra ID or Google Workspace connects as an oidc connection bound to an organization, found by email domain on the login screen (Pro). To sign your users in to an application that only accepts SAML, use SAML for your apps instead — that is a client setting, not a connection. Not available yet: SMS one-time codes and SAML identity providers as connections.

What users sign in with

A database connection decides what its users type in the sign-in field — login_identifier:

The server enforces it, not just the screen: under email, a username does not sign anyone in, and under username, an email does not.

New database connections use email. A connection created before this setting existed behaves as email_or_username, which is what the login always did, until you change it. Change it under Sign-in identifier on the connection’s page in the dashboard, or over the API:

POST /connection/<connection_id>
Content-Type: application/json
 
{ "login_identifier": "email" }

Usernames are set on a user’s credential with the Management API. Before switching a connection to email, make sure none of its users signs in by username only — they would not be able to sign in.

Using Connections for OAuth Login

When a developer uses Faable Auth to implement a login flow (such as the standard OAuth2 Authorization Code flow), the concept of a connection is crucial.

1. Creation: First, you create and configure a Connection in the Faable Dashboard (e.g., you create a Google social connection and provide your Google Client ID and Secret). Each connection is assigned a unique name.
2. Authentication Request: When your application redirects the user to the Faable Auth /authorize endpoint to log in, you can optionally include the connection_id parameter in the URL.
   • If you specify a specific connection (e.g., connection_id=connection_abc123, shown in the dashboard), Faable Auth will directly redirect the user to that provider’s login page, bypassing the generic login screen. connection is an alias of the same parameter and also takes the id: a connection name is refused.
   • If you don’t specify a connection, Faable Auth will display the Universal Login screen, presenting the user with options for all the connections that are enabled for your client application (e.g., an email/password form alongside a “Log in with Google” button).
   • A connection belongs to one tenant, so a connection_id copied from another tenant — production’s, on a test client — is refused with invalid_connection. The error page names the id and the connection types the client offers. If your test tenant needs the same login, create the connection there and use its own id, as described in Test and production tenants.
   • A client needs at least one connection offered to it. Without one, a login that names no connection is refused with connection_required, and the client’s page in the dashboard warns you.
3. Unified Profile: Regardless of the connection used to log in, Faable Auth normalizes the user data. It handles the specific handshake with the external provider and returns a standard set of OAuth2/OIDC tokens (Access Token, ID Token) to your application. This means your application’s logic remains exactly the same whether the user logged in with a password, a magic link, or their GitHub account.

Next Steps

Now that you understand what Connections are, you can learn how to integrate them into your application by exploring the following topics:

• Clients: Learn how to register your front-end application or backend API to use these connections.
• OAuth 2.0 Flows: Choose the right flow for your application type.
• Authorization Code Flow: Understand the standard OAuth2 flow used to redirect users to Faable Auth and handle the login callback.
• Social Login: Set up Google, GitHub or Microsoft sign-in from one place.
• Passwordless: Magic links and one-time codes, no password to remember.
• Quickstart Next.js: Jump straight into the code and see a full authentication implementation in action.
• Quickstart React Native: Jump straight into the code and see a full authentication implementation in action.

Last updated on November 4, 2026