# OAuth

BetterForms currently supports OAuth login with:

* `google`
* `auth0`
* `okta`

Use OAuth when you want the provider to authenticate the user while BetterForms still creates or updates the app user and signs them into the app.

## What You Need

* OAuth credentials configured for the app or tenant
* A `Users.oauthId` field in your helper file, available on the `Users` layout
* A callback page with the navigation slug `auth/oauth`
* `authLoginOauth` on that page's `onFormLoad`

If you want BetterForms to create users who do not already exist, you also need the `onBeforeRegistration` server hook.

## Provider Callback URL

In your OAuth provider settings, use this callback pattern:

```
https://your.domain.com/oauth/{provider}/callback
```

Examples:

* `https://your.domain.com/oauth/google/callback`
* `https://your.domain.com/oauth/auth0/callback`
* `https://your.domain.com/oauth/okta/callback`

## Typical Flow

1. Add a button or link that navigates to `/oauth/{provider}`.
2. The provider authenticates the user and returns to BetterForms.
3. BetterForms redirects the browser to your `auth/oauth` page.
4. Your `auth/oauth` page runs `authLoginOauth`.
5. BetterForms stores the token and continues through the normal login flow.

## Callback Page

Add `authLoginOauth` to the page's `onFormLoad` action:

```json
"onFormLoad": [
  {
    "action": "authLoginOauth"
  }
]
```

`oauthLoginHook` is a legacy alias and is still supported, but `authLoginOauth` is the preferred name.

## How User Matching Works

* BetterForms looks up users by email from the provider response.
* If the user already exists, BetterForms updates `oauthId` when needed and signs the user in.
* If the user does not exist, BetterForms calls `onBeforeRegistration`.
* New user creation only continues when that hook returns `model.createUser = true`.
* New users created through OAuth are automatically verified.

## Minimal Login Example

Start the flow with a `path` action:

```json
{
  "action": "path",
  "options": {
    "sameWindow": true,
    "url": "/oauth/google"
  }
}
```

## Notes

* If OAuth login fails, BetterForms returns an `errorMessage` to the callback page and `authLoginOauth` sends it through the normal BetterForms error pipeline.
* Any query params you append to the initial OAuth URL are also available to `onBeforeRegistration` if you need them for registration logic.
* For an Auth0-specific walkthrough, see [Setting Up Auth0](/reference/apis-and-services/integrations/setting-up-auth0.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.klai.studio/reference/authentication/oauth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.