Create a custom connector

<head> <script type=“application/ld+json”> {{"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Do workspace members need their own account with the API?", "acceptedAnswer": {"@type": "Answer", "text": "Not necessarily. One person connects to the connector using credentials from the API provider, such as an API key. They can then share that connection with specific people or with the entire workspace. Everyone with access builds with the shared connection, without needing their own account. A member only needs their own credentials if they create a separate connection of their own."}}, {"@type": "Question", "name": "Can I change the authentication method after creating a connector?", "acceptedAnswer": {"@type": "Answer", "text": "Partially. You can switch between the single-credential methods: bearer token, custom header, or query parameter. You can also move any credential-based method to Advanced. Two restrictions apply: a connector can't switch between OAuth 2.0 and credential-based authentication, and existing credential field keys stay locked. Existing connections store their credentials in the current structure, and changing it would break them."}}, {"@type": "Question", "name": "What happens when I delete a custom connector?", "acceptedAnswer": {"@type": "Answer", "text": "RShift Sites removes the connector definition and deletes its existing connections, including their stored credentials. Apps that use those connections stop working. Deletion cannot be undone."}}, {"@type": "Question", "name": "Who can see the credential values users enter?", "acceptedAnswer": {"@type": "Answer", "text": "Credential values are stored encrypted, and the connector gateway injects them into requests server-side. They never appear in the project chat or in project code. Members the connection is shared with can view its configuration: values marked secret, such as API keys and tokens, appear masked and show only their last few characters, while fields not marked secret, such as a basic auth username, are visible in full."}}]}} </script> </head>

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 RShift Sites 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: the apps you build use them to call the API, and RShift Sites can work with them while you build, guided by the knowledge files you add. To only bring context from your tools into your conversations with RShift Sites, use a custom MCP server as a chat connector instead.

Who can create connectors

Creating 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.

After creation, 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 entire connector in a single form with three sections, Details, Authentication, and Agent knowledge, opened from the + button in the connector catalog:

Open the create form

Open Connectors, select the + button in the top right of the catalog, and choose Custom connector (“Connect an API to your workspace”). This opens the Create custom connector form. When you search the catalog, a Custom card (“Connect your own API”) appears in the results and opens the same form.

Describe your connector

Under Details, fill in the following fields:

• 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.
• Logo (optional): select Upload logo to add the logo users see in the catalog.
• 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.

Choose an authentication method

Under Authentication, pick how the API expects credentials (see Authentication methods below). For non-OAuth methods, a live preview, What requests to this API will look like, shows the resulting request 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.

Set the API base URL and test request

Also under Authentication, set:

• API base URL: where requests are sent. Must be an https:// URL.
• Under Test request, a Method and Path: an endpoint RShift Sites calls to verify credentials when a user connects (for example, GET /v1/me). The path must start with /.

Add knowledge (optional)

Under Agent knowledge, fill in the first knowledge file’s Name, Description, and Content, and select Add knowledge file to add another. Knowledge files teach RShift Sites how to use the API: key endpoints, request formats, pagination rules, and common pitfalls. Good knowledge files significantly improve how well RShift Sites uses your connector. See Writing connector knowledge files for guidance and an example.

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.

Authentication methods

Pick the method that matches how your API expects credentials:

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 (Proof Key for Code Exchange), an extension that adds an extra verification step to the authorization flow.

After you enter the API base URL, the form displays a redirect URL under Add this redirect URL to the service’s OAuth app settings. 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 RShift Sites learns to use your API. Without them, RShift Sites only knows your base URL and authentication method, so it has to guess endpoint paths, parameter names, and response formats. A good knowledge file removes the need to guess, so treat it as documentation written for RShift Sites rather than for humans.

They are separate from workspace and project knowledge: connector knowledge is part of the connector definition 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 RShift Sites 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, including the endpoints, examples, and caveats.

What to include

Follow the same structure RShift Sites 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). RShift Sites 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 request body, required parameters, and query options.
4. Response formats: mention wrappers and field names RShift Sites should expect (for example, “responses are wrapped in a top-level data field”).
5. A notes section for details that commonly cause integration errors: pagination parameters, rate limits, API versioning in paths, async operations, and date or ID formats.

What to leave out

Some content does not 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: RShift Sites doesn’t need instructions for attaching credentials. The connector handles it.
• Marketing copy: promotional language does not help RShift Sites call the API. Keep knowledge files technical and factual.

Example

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

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.

<Aside type="tip">

You can split knowledge across multiple files, for example one for core concepts and endpoints, and another for a complex sub-domain such as reporting or webhooks. Each file's **Description** helps RShift Sites pick the right one for the task. A connector can have up to 50 knowledge files, each file's content can be up to 50,000 characters, and the connector definition as a whole, including all knowledge files, can be up to 256 KB.

</Aside>


## 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 select **Add connection**.
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. Under **Sharing**, they choose who can use it: only themselves, specific people, or the entire workspace. A new connection is private to its creator by default and shows a **Private** label. See [Who can use connections and clients](/sites/integrations/admin-controls/#who-can-use-connections-and-clients).
4. RShift Sites verifies the credentials by calling the test request you configured.
5. When connected, the connection can be [linked to projects](/sites/integrations/app-connectors/#link-a-connection-to-a-project), and RShift Sites 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 → App + chat connectors**, under **Custom connectors**. The admin settings area is available on Business and Enterprise plans:

* **Availability**: control who can create connections (**No one**, **Editors & admins**, or **Admins**), the same way as for any other connector. A newly created connector starts at **Admins**. Free and Pro plans have no picker: any workspace member with the editor role or higher can create connections. See [Manage connectors in your workspace](/sites/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 in their current structure: 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.


<Aside type="danger">

Deleting a connector removes its definition from the workspace and **deletes its existing connections**, including their stored credentials. Apps that use those connections stop working. This cannot be undone.

</Aside>


## Security

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

* Credential values are entered only when a connection is created, and are stored encrypted by RShift Sites. They are injected into requests server-side by the connector gateway, and never appear in the project chat or in project code. Members with access to a connection can view its configuration, where secret values appear masked.
* 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.

## FAQ


**Do workspace members need their own account with the API?**

Not necessarily. One person connects to the connector using credentials from the API provider, such as an API key. They can then share that connection with specific people or with the entire workspace. Everyone with access builds with the shared connection, without needing their own account. A member only needs their own credentials if they create a separate connection of their own.


  

**Can I change the authentication method after creating a connector?**

Partially. You can switch between the single-credential methods: bearer token, custom header, or query parameter. You can also move any credential-based method to **Advanced**. Two restrictions apply: a connector can't switch between OAuth 2.0 and credential-based authentication, and existing credential field keys stay locked. Existing connections store their credentials in the current structure, and changing it would break them.


  

**What happens when I delete a custom connector?**

RShift Sites removes the connector definition and deletes its existing connections, including their stored credentials. Apps that use those connections stop working. Deletion cannot be undone.


  

**Who can see the credential values users enter?**

Credential values are stored encrypted, and the connector gateway injects them into requests server-side. They never appear in the project chat or in project code. Members the connection is shared with can view its configuration: values marked secret, such as API keys and tokens, appear masked and show only their last few characters, while fields not marked secret, such as a basic auth username, are visible in full.


## Related topics

- [Connect a custom MCP server as a chat connector](/sites/integrations/custom-mcp/)
- [RShift Sites connectors: Connect tools, services, and APIs](/sites/integrations/introduction/)
- [Subscription plans](/sites/introduction/subscription-plans/)
- [Integrate any API with RShift Sites](/sites/integrations/any-api/)