> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/build/integrations/connectors/auth-methods.md).

# Auth methods and providers

The Auth tab: a connector's authentication methods, the default method, and the OAuth apps (auth providers) behind them.

An **auth method** is one way a customer can prove who they are to the app: sign in with OAuth, paste an API key, enter a username and password. An **auth provider** is the OAuth app (a client ID and client secret registered with the vendor) that an OAuth method uses to send people to the vendor's consent screen.

### The Auth tab

> How your customers prove who they are. The default is used unless a connection picks another.

One row per method. Each row shows:

* the method's **name**, for example *OAuth 2.0* or *API Key (Bearer)*;
* **Default** on the default method;
* a plain-language description of what the customer does:
  * OAuth: *Your customers sign in with the provider and approve access.*
  * Keys and tokens: *Your customers paste a key they generate themselves.*
* for OAuth methods, how many providers it has, for example *1 provider*.

The method types, and the fields each one asks for, are listed in [Creating a connector → Authentication](https://docs.fastn.ai/build/integrations/connectors/creating-a-connector.md#authentication). Each type is stored as a value such as `OAUTH_2`, `API_KEY`, `BEARER`, `BASIC`, `DIGEST`, `INPUT` or `NO_AUTH`. The header line and the [Connections](https://docs.fastn.ai/operate/connections.md) page show readable labels instead, for example *OAuth 2.0*, *API key* or *Custom*.

### Auth providers

**View providers** lists the OAuth apps behind the connector's OAuth methods.

| Column        | Meaning                                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**      | The provider's name, for example *HubSpot OAuth*.                                                                                                |
| **Client ID** | The OAuth client ID registered with the vendor. The client secret is never shown.                                                                |
| **Preferred** | **Preferred app** marks a default provider. Your own app and the community app can both show it; the connect dialog shows which one it will use. |
| **Used By**   | Which connections use this provider.                                                                                                             |
| **Actions**   | What you can do with it. *Community - read-only* means the provider belongs to fastn's shared catalog and cannot be changed from your workspace. |

The **‹** arrow returns to the method list.

#### Using your own OAuth app

Every fastn-managed OAuth connector ships with a **community app** (shown as "\[Connector] OAuth"). It works out of the box but is read-only and shared across fastn customers. A connector your workspace built has no community app, so it has no provider until you create one. An **auth provider** is a set of OAuth credentials that fastn uses when your customers sign in to a connector. Creating your own provider lets you:

* Show your own app name and logo on the service's consent screen when sign-in goes through your app (see Step 6).
* Control exactly which scopes are requested.
* Use your own API rate limits instead of shared ones.
* Rotate or revoke credentials without contacting fastn.

You need a role that can create connectors in your fastn workspace (Owner, Admin, Developer or Operator) to follow these steps. On a fastn-managed connector, your workspace also needs custom OAuth apps allowed. This is on by default; if fastn has turned it off for your workspace, you can view the providers but not add your own.

**Before you begin**

Have these ready before you open fastn.

* A developer app (created in the connected service's developer portal) with OAuth enabled.
* The app's **Client ID** and **Client Secret**.
* The scopes your integration needs, for example `contacts:read`. They must match the scopes configured on the developer app.
* The service's **Authorization URL** and **Token URL** (from the service's OAuth documentation).
* fastn's redirect (callback) URL, `https://oauth.live.fastn.ai`, registered in your developer app's OAuth settings. The service rejects sign-ins when it does not match.
* One of the roles above in your fastn workspace.

**Step 1: Open the connector**

Start in **Integrations**, then open the connector you want to configure.

1. In the left sidebar, under **Build**, click **Integrations**.
2. Make sure the **Connectors** tab is selected at the top of the page.
3. Type the connector's name in the search box. The matching card appears, grouped under a category such as **CRM & Sales**.
4. Click the connector card. A green **Connected** badge means the connector is already available in your workspace; this does not mean your own credentials are in use yet.

<figure><img src="https://1255842839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3iSr2Tx8FvvuoLPncziH%2Fuploads%2Fgit-blob-e543cf016bf55fda42ae761a8627772c203c1b88%2Fown-oauth-app-1-connectors.webp?alt=media" alt="Integrations, Connectors tab, with hubspot typed in the search box and a single HubSpot card in CRM and Sales, badged Connected, OAuth 2.0 and Managed by Fastn"><figcaption><p>Find the connector under <strong>Integrations</strong> → <strong>Connectors</strong>.</p></figcaption></figure>

**Step 2: Open the Auth tab**

Authentication settings live on the connector's **Auth** tab, not on the connector list.

1. On the connector page, click the **Auth** tab. The other tabs are **Overview**, **Connections**, **Version pins** and **Webhook config**.
2. Under **Authentication methods**, you will see **OAuth 2.0** marked **Default**. On a fastn-managed connector it shows "1 provider" on the right: the community app.
3. Click **Manage providers** at the top right of the panel. The button reads **Add provider** when the connector has no providers yet, and **View providers** when you can't add one.

<figure><img src="https://1255842839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3iSr2Tx8FvvuoLPncziH%2Fuploads%2Fgit-blob-5425181fec50492e640a780dfb1d92323936e6aa%2Fown-oauth-app-2-auth-tab.webp?alt=media" alt="The HubSpot connector&#x27;s Auth tab: Authentication methods lists OAuth 2.0 marked Default with 1 provider, and a Manage providers button at the top right"><figcaption><p>The <strong>Auth</strong> tab, with <strong>Manage providers</strong> at the top right.</p></figcaption></figure>

**Step 3: Review existing providers**

The **Auth Providers** page lists every set of OAuth credentials for this connector, with columns for **Name**, **Client ID**, **Preferred**, **Used By** and **Actions**.

* **\[Connector] OAuth** is the community app. It carries the **Preferred app** badge and the label "Community - read-only", so you cannot edit or delete it.
* Your own providers appear below it once created, with **Edit** and **Delete** actions.

Click **+ Create Provider** at the top right to add your own.

**Step 4: Enter your app's identity and scopes**

The **New Auth Provider** dialog opens. Fill in the top section first.

1. **Name**: a label your team will recognize, for example *My Company \[Connector] App*.
2. **Description** (optional): a note such as "Production credentials".
3. **Client ID**: paste the Client ID from your developer app on the service you are connecting.
4. **Client Secret**: paste the Client Secret from the same app. Treat it like a password.
5. **Scopes**: type a scope in the format the service uses and press Enter (or click **Add**), for example `contacts:read`. Repeat for each scope.
   * Use **+ Detailed** to add a scope with a label and description.
   * Use **+ Group** to bundle related scopes together.

Scroll down in the dialog to continue. The **Create** button stays disabled until the required fields are filled.

**Step 5: Set the endpoints and grant types**

Scroll to the lower half of the dialog. The grey placeholders in the fields are examples only; replace them with the endpoints published in the service's OAuth documentation.

| Field                        | What to enter                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------------- |
| **Response Type**            | `code` (pre-filled; leave as is for the standard authorization code flow)                      |
| **Authorization URL**        | The service's OAuth authorize endpoint, for example `https://auth.example.com/oauth/authorize` |
| **Token URL**                | The service's token endpoint, for example `https://auth.example.com/oauth/token`               |
| **Grant Type**               | **Authorization code (with grant\_type)**, the default                                         |
| **Token Grant Type**         | **Refresh token (with grant\_type)**, the default                                              |
| **URL Variables** (optional) | Fill only if the service's URLs contain account-specific parts, such as a subdomain or region  |

Confirm the URLs and grant types against the service's OAuth documentation before saving, since providers can change endpoints.

Click **Create** when every field is filled.

**Step 6: Make your app preferred**

After you click **Create**, your provider appears in the list under the community app, for example "My Company Custom App". It is not your preferred app yet: only the community app has the **Preferred app** badge.

1. In your provider's row, click **Use this app** in the **Preferred** column. Your app gets the **Preferred app** badge. The community app keeps its own badge, so both rows show it.
2. Check the Client ID in the row matches the one in your developer app.
3. Open the **Connections** tab and create a test connection. The connect dialog shows the provider it will use; if it isn't your app, pick yours under **⋯** → **Change provider**. The service's consent screen should then show your app's name. If it still shows the community app, contact fastn.

To change credentials later, click **Edit** on your provider's row. **Delete** is available only when no active connection uses the provider.

**Security and troubleshooting**

| Symptom                                      | Likely cause                                                                      | Fix                                                                                                                                                                                                                                            |
| -------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Create** button is greyed out              | A required field is empty                                                         | Fill **Name**, **Client ID** and **Client Secret**, then retry                                                                                                                                                                                 |
| The service shows a redirect URI error       | fastn's callback URL is not registered in your developer app                      | Add the exact callback URL in the app's OAuth settings on the service. Some services, such as Airtable, expect it with a trailing slash (`https://oauth.live.fastn.ai/`). If the error persists with the URL registered exactly, contact fastn |
| The service shows an invalid scope error     | A scope in fastn is not enabled on the developer app                              | Make the scope lists match in both places                                                                                                                                                                                                      |
| Consent screen still shows the community app | Both apps show **Preferred app**, and the connect dialog picked the community app | For a test connection in the dashboard, pick your app under **⋯** → **Change provider**. Customers connecting in the widget can't choose, so if they keep getting the community app, contact fastn                                             |
| Sign-in fails after a secret change          | fastn still holds the old secret                                                  | Edit the provider and paste the new **Client Secret**                                                                                                                                                                                          |

### How the default method is chosen

* The connect dialog opens with the **default** method selected.
* If the connector offers more than one method, the dialog has an **Auth Method** selector, so the person connecting can choose another (for example Airtable offers *OAuth 2.0* and *Bearer Token*).
* The method chosen is saved on the connection. You see it in the **Auth** column on the [Connections](https://docs.fastn.ai/operate/connections.md) page.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fastn.ai/build/integrations/connectors/auth-methods.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
