> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom connector

> Build your own connector for any REST API, public or internal, and make it available to your Lovable workspace. Define the endpoint, authentication, and knowledge once, and let everyone in your workspace connect to it like any other app connector.

You can create your own connector for any REST API, whether it's a public third-party API or an internal service, and make it available to your Lovable workspace. You define the connector once (its API endpoint, authentication method, and optional knowledge files), and everyone in your workspace can then connect to it like any other app + chat connector.

Connectors you create are [app + chat connectors](/integrations/app-connectors): the apps you build use them to call the API, and Lovable can work with them while you build, guided by the knowledge files you add. To only bring context from your tools into the Lovable chat, use a [custom MCP server as a chat connector](/integrations/custom-mcp) instead.

## Who can create connectors

Creating and managing connectors requires the workspace **admin** or **owner** role, and is available on all plans. Connectors you create are scoped to a single workspace: they appear in that workspace's connector catalog and are not visible to other workspaces.

Once created, workspace members connect to your connector the same way they connect to any other app + chat connector.

## How to create a connector

You define the whole connector in a single form, opened from the connector catalog:

<Steps>
  <Step title="Open the connector catalog">
    Go to **Connectors** in your workspace. In the connector catalog, select the **Custom** card ("Connect your own API"). This opens the **Create custom connector** form.
  </Step>

  <Step title="Describe your connector">
    Fill in the basic details:

    * **Display name**: the name users see in the catalog. Use the name of the API the connector reaches (for example, `Acme Projects API`). The connector's internal ID is derived from this name and can't be changed later.
    * **Short description**: a one-line summary (for example, `Project management boards`).
    * **Description**: a longer explanation of what the connector does.
    * **Category**: where the connector appears in the catalog (Productivity, Sales, Marketing, E-commerce, Support, Messaging, Development, Payments, or Other).
    * **Documentation URL** (optional): a link to the API's documentation.

    Under **Created by**, enter the provider **Name** and **Homepage URL**. These are shown to users so they know who is behind the API.
  </Step>

  <Step title="Configure the API endpoint">
    Under **API endpoint**, set:

    * **API base URL**: where requests are sent. Must be an `https://` URL.
    * **Method** and **Verification path**: an endpoint Lovable calls to verify credentials when a user connects (for example, `GET /v1/me`). The path must start with `/`.
  </Step>

  <Step title="Choose an authentication method">
    Under **Authentication**, pick how the API expects credentials (see [Authentication methods](#authentication-methods) below). For non-OAuth methods, a live preview shows **what the agent's requests will look like** with your configuration applied.

    Credential *values* are never entered in this form. Users provide their own API key or OAuth client credentials when they create a connection.
  </Step>

  <Step title="Add knowledge (optional)">
    Under **Knowledge**, click **Add knowledge file** to teach Lovable how to use the API: key endpoints, request formats, pagination rules, or gotchas. Each knowledge file has a **Name**, **Description**, and **Content**. Good knowledge files dramatically improve how well Lovable uses your connector. See [Writing connector knowledge files](#writing-connector-knowledge-files) for guidance and an example.
  </Step>

  <Step title="Create the connector">
    Click **Create**. The connector now appears in your workspace's connector catalog, and in the **Custom connectors** section of the connector admin settings.
  </Step>
</Steps>

## Authentication methods

Pick the method that matches how your API expects credentials:

| Method                               | How credentials are sent                                                               | What you configure                                                                                                                               |
| :----------------------------------- | :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bearer token**                     | `Authorization: Bearer <token>` header                                                 | Nothing extra. Users paste their token when connecting.                                                                                          |
| **API key in a custom header**       | A header you name (for example, `X-Api-Key`)                                           | **Header name** and an optional **Value prefix**.                                                                                                |
| **API key in a query parameter**     | A query parameter you name (for example, `?key=...`)                                   | **Parameter name**.                                                                                                                              |
| **Basic auth (username & password)** | `Authorization: Basic ...` header                                                      | Nothing extra. Users enter a username and password when connecting.                                                                              |
| **Advanced**                         | Multiple credential fields, each sent as a header, query parameter, or basic auth part | One or more fields, each with a **Field key**, **Label**, **Send as** option, and a **Secret** toggle. At least one field must be marked secret. |
| **OAuth 2.0**                        | Standard OAuth 2.0 authorization code flow                                             | Authorization URL, token URL, scopes, and PKCE (see below).                                                                                      |

### Setting up OAuth 2.0

For APIs that use OAuth 2.0, configure:

* **Authorization URL** and **Token URL**: your provider's OAuth endpoints (both must be `https://`).
* **Scopes** (optional): one per line, or separated by spaces or commas.
* **Scope separator** (optional): leave blank for the default (space). Some providers require a comma.
* **Use PKCE**: enable if your provider supports or requires PKCE.

The form displays a **Redirect URI to register with your provider**. Copy it and add it to your OAuth app's allowed redirect (callback) URLs. It must match exactly.

## Writing connector knowledge files

Connector knowledge files are how Lovable learns to use your API. Without them, Lovable only knows your base URL and authentication method, so it has to guess endpoint paths, parameter names, and response shapes. A good knowledge file removes the guesswork, so treat it as documentation written for Lovable rather than for humans.

They are separate from [workspace and project knowledge](/features/knowledge): connector knowledge travels with the connector and only covers how to call its API.

Each knowledge file has three parts:

* **Name**: a short identifier (for example, `Acme Projects API basics`).
* **Description**: a one-line summary of what the file covers, so Lovable picks the right file for the task (for example, `Endpoints and request formats for reading and writing Acme Projects boards and tasks.`).
* **Content**: the actual instructions, in Markdown. This is where the endpoints, examples, and gotchas go.

### What to include

Follow the same structure Lovable uses for its built-in connectors:

1. **A one-line summary** of what the API does and what it's for.
2. **Key endpoints**: method, path, and what each does. Use paths relative to your API base URL (for example, `GET /v1/tasks`). Lovable routes requests and attaches credentials automatically, so don't hardcode full URLs or authentication headers.
3. **Request examples** for the most common operations, as code blocks. Show the exact body shape, required parameters, and query options.
4. **Response shapes**: mention wrappers and field names Lovable should expect (for example, "responses are wrapped in a top-level `data` field").
5. **A notes section** for the things that trip up integrations: pagination parameters, rate limits, API versioning in paths, async operations, and date or ID formats.

### What to leave out

A few things don't belong in knowledge files:

* **Credentials or secrets**: never put tokens, keys, or client secrets in knowledge content. Authentication is configured separately and injected automatically.
* **Authentication boilerplate**: Lovable doesn't need instructions for attaching credentials. The connector handles it.
* **Marketing copy**: descriptions of how great the product is waste context. Stick to technical facts.

### Example

A knowledge file for the fictional `Acme Projects API`, a project management API:

````markdown theme={null}
This connector calls the Acme Projects API to manage projects and tasks.

## Key endpoints

- `GET /v1/projects`: list projects
- `GET /v1/projects/{id}/tasks`: list tasks in a project
- `POST /v1/tasks`: create a task
- `PATCH /v1/tasks/{id}`: update a task (status, assignee, due date)

## Creating a task

```json
POST /v1/tasks
{
  "project_id": "proj_123",
  "title": "Draft launch plan",
  "due_on": "2026-08-01",
  "assignee_id": "user_456"
}
```

## Notes

- All responses are wrapped in a top-level `data` field.
- List endpoints are paginated: pass `limit` (max 100) and the `next_cursor`
  value from the previous response.
- Dates use `YYYY-MM-DD` format; timestamps are ISO 8601 in UTC.
- Rate limit is 60 requests per minute; batch operations should back off
  on `429` responses.
````

<Tip>
  You can split knowledge across multiple files, for example one for core concepts and endpoints, and another for a complex sub-domain like reporting or webhooks. Each file's **Description** helps Lovable pick the right one for the task at hand. A connector can have up to 50 knowledge files, and each file's content can be up to 50,000 characters.
</Tip>

## Using your connector

After creation, your connector behaves like any other app + chat connector:

1. Users open **Connectors**, find your connector in the catalog, and click **Connect**.
2. They enter the credential values you defined (an API key, username and password, or OAuth Client ID and secret). For OAuth connectors, a popup runs the authorization flow with your provider.
3. They choose who can use the connection: only themselves (the default), specific people, or the whole workspace. See [Who can use connections](/integrations/admin-controls#who-can-use-connections-and-clients).
4. Lovable verifies the credentials against the **Verification path** you configured.
5. Once connected, the connection can be [linked to projects](/integrations/app-connectors#link-a-connection-to-a-project), and Lovable can build apps that call your API, guided by any knowledge files you added.

## Managing connectors

Workspace admins and owners manage the connectors created in their workspace from **Connectors → Admin settings**, under **Custom connectors**:

* **Availability**: control who can create connections (**No one**, **Admins**, or **Editors & admins**), the same way as for any other connector. The per-connector picker is available on Business and Enterprise plans. On Pro, any workspace member with the editor role or higher can create connections. See [Manage connectors in your workspace](/integrations/admin-controls) for the defaults on each plan.
* **Edit**: update the connector's details, endpoint, knowledge, and authentication configuration. Some authentication changes are restricted because existing connections store credentials under the current shape: a connector can't switch between OAuth 2.0 and credential-based authentication, and existing credential field keys are locked. You can still switch between the single-credential methods (bearer token, custom header, or query parameter), or move any credential-based method to **Advanced**.
* **Delete**: remove the connector definition from the workspace.

<Warning>
  Deleting a connector removes its definition from the workspace, and **existing connections for it stop working**. This cannot be undone.
</Warning>

## Security

Custom connectors follow the same security model as built-in connectors, described in [Integration security](/integrations/security):

* Credential values are entered only when a connection is created, and are stored encrypted by Lovable. They are injected into requests server-side by the connector gateway, and are never exposed in chat, in project code, or to other users.
* Workspace-shared connections can be used by other members of the workspace, so only share connections whose data you're comfortable making available to your team.


## Related topics

- [Subscription plans](/introduction/subscription-plans.md)
- [Connect a custom MCP server as a chat connector](/integrations/custom-mcp.md)
- [Lovable connectors: Connect tools, services, and APIs](/integrations/introduction.md)
- [Manage connectors in your workspace](/integrations/admin-controls.md)
- [Connect your app to Wave](/integrations/wave.md)