Skip to Content
🔐 Faable AuthConnections

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:

connection_typeCategoryWhat it is
databasedatabaseEmail + password. Faable Auth stores and manages the credentials on your behalf.
google_oauth2socialGoogle sign-in. Endpoints preconfigured.
githubsocialGitHub sign-in. Endpoints preconfigured.
microsoftsocialMicrosoft / Entra ID — work, school and personal Microsoft accounts. Endpoints preconfigured.
figmasocialFigma sign-in. Endpoints preconfigured; bring your own OAuth app.
customsocialAny other OAuth 2.0 provider — you supply the authorize, token and userinfo URLs. See Facebook for a worked example.
passwordless_emailpasswordlessMagic link or one-time code by email. The address itself is the identity.
oidcoidcAn external OIDC issuer whose JWTs are trusted in a Token Exchange — GitHub Actions being the canonical case. Machine-to-machine, not a browser login.

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

Not available yet: SMS one-time codes, SAML, and any pre-built enterprise SSO connector (Okta, Entra ID as an enterprise connection rather than a social one). For an OIDC-compliant corporate IdP, a custom connection covers browser login today, as long as its userinfo endpoint returns id, name and email.

What users sign in with

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

login_identifierUsers sign in withThe hosted login screen
emailtheir email addressAsks for an email and checks the format before sending it
usernametheir usernameAsks for a username
email_or_usernameeither — the email is tried firstAsks for “email or username” and accepts both

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. (The legacy connection parameter, which takes the connection name, is still accepted as a deprecated alias.)
    • 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).
  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

ClientsOverview