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

# Creating a System

> Connect superglue to any system

Create a system in superglue to use as reusable building blocks for building tools in superglue. Systems handle authentication and documentation retrieval automatically once configured.

## Getting started

<Tabs>
  <Tab title="Via Agent">
    The fastest way to create a system is through the agent interface. Visit [app.superglue.cloud](https://app.superglue.cloud) and start chatting with the agent.

    <video autoPlay muted loop playsInline className="w-full rounded-lg">
      <source src="https://mintcdn.com/superglue/u32I4ezswr71mkrq/resources/creating-a-system-via-agent.mp4?fit=max&auto=format&n=u32I4ezswr71mkrq&q=85&s=cd8162d0caeeca25ffa1db91467d07e0" type="video/mp4" data-path="resources/creating-a-system-via-agent.mp4" />
    </video>

    superglue will:

    1. Identify the target system
    2. Guide you through the authentication flow by collecting all required credentials
    3. Create the system and make it available immediately
    4. Process and analyze the system's documentation automatically in the background
    5. Test system access and verify your credentials are working

    <Card icon="plug" href="https://app.superglue.cloud" horizontal>
      Start creating systems with the agent
    </Card>
  </Tab>

  <Tab title="Via UI">
    Systems can also be created manually using the web application:

    <Steps>
      <Step title="Navigate to systems">
        Click the "Systems" button in the sidebar
      </Step>

      <Step title="Open form">
        Click **Add System** to open the system form
      </Step>

      <Step title="Fill required fields">
        * **Template**: Choose from 100+ prebuilt templates or create a custom system. Templates pre-fill the base URL, documentation URL, and authentication type
        * **URL**: Base URL of the system (e.g., `https://api.stripe.com`)
        * **Documentation URL**: Optional but recommended link to API documentation
        * **Documentation as a file**: Optionally upload a documentation file (PDF, OpenAPI Specs, .zip files, etc.). If you upload a file, superglue will not crawl a doc URL.
        * **Credentials**: See [authentication and credential management](/guides/creating-a-system#authentication-and-credential-management) for details
        * **OAuth**: For OAuth systems, click **Connect to system** to complete the flow and let superglue handle the token exchange
      </Step>

      <Step title="Click 'Add System'">
        superglue saves your configuration and processes online documentation in the background if a documentation URL was provided
      </Step>
    </Steps>

    <video autoPlay muted loop playsInline className="w-full rounded-lg">
      <source src="https://mintcdn.com/superglue/u32I4ezswr71mkrq/resources/creating-a-system-ui.mp4?fit=max&auto=format&n=u32I4ezswr71mkrq&q=85&s=c6b48467922089287ef0885093599dbf" type="video/mp4" data-path="resources/creating-a-system-ui.mp4" />
    </video>
  </Tab>
</Tabs>

## Authentication and credential management

superglue supports many different authentication methods. All credentials are encrypted both at rest and in transit.

<AccordionGroup>
  <Accordion title="OAuth" icon="user-lock">
    superglue supports both the client credentials flow and authorization code flow with **automatic token refresh**.

    **superglue handles:**

    * Scope validation
    * Token exchange and storage
    * Error handling for token issues
    * Automatic token refresh during tool execution

    #### Authorization code flow

    Used when users grant access to their account data.

    1. User clicks the "connect to provider" button
    2. Redirected to the provider’s login page
    3. User grants permissions for requested scopes
    4. superglue exchanges the authorization code for access tokens
    5. Tokens are automatically refreshed on expiration

    **Examples:** Slack, Salesforce, Google Services

    ### Client credentials flow

    Used for server-to-server communication with no user interaction.

    1. Application requests an access token using client ID and secret
    2. Token is automatically refreshed before expiration
    3. No user consent required

    **Examples:** Twilio, Auth0 Management API, Microsoft Graph

    **Required fields:**

    * `clientId`, `clientSecret`, `authorizationUrl`, `tokenUrl`

    **Optional fields:**

    * `scopes`: space-separated OAuth scopes
    * `redirectUri`: redirect URL after authorization

    <Info>
      Prebuilt OAuth templates are available for 100+ APIs including HubSpot, Google Ads, and Salesforce. Check the templates dropdown in the creation form.
    </Info>
  </Accordion>

  <Accordion title="API keys" icon="key">
    The simplest authentication method. Provide an API key and superglue automatically determines where to include it based on the API’s documentation.

    Possible placements:

    * Authorization header: `Authorization: Bearer {key}`
    * Custom header: `X-API-Key: {key}`
    * Query parameter: `?api_key={key}`

    ### Examples

    * **SendGrid**: API key in Authorization header with Bearer prefix
    * **Airtable**: Personal access token as Bearer token
    * **Zendesk**: Email + API token combined as basic auth (`{email}/token:{apiKey}`)
    * **Shopify**: Custom header `X-Shopify-Access-Token`
    * **Mailchimp**: Basic auth with `anystring` as username and API key as password
  </Accordion>

  <Accordion title="Data storage connections" icon="database">
    Connect to databases and data stores by providing connection details. Supported types include PostgreSQL, MSSQL, Redis, and FTP/SFTP servers.

    ### Configuration

    **PostgreSQL** requires a connection URL in the format `postgresql://<<user>>:<<password>>@<<host>>:<<port>>/<<database>>` with credentials for `user`, `password`, `host`, `port`, and `database`.

    **MSSQL** requires a connection URL in the format `mssql://<<user>>:<<password>>@<<host>>:<<port>>/<<database>>` with credentials for `user`, `password`, `host`, `port`, and `database`. For Azure SQL, use the fully qualified server name (e.g., `myserver.database.windows.net`).

    **Redis** requires a connection URL in the format `redis://<<user>>:<<password>>@<<host>>:<<port>>/<<database>>` (or `rediss://` for TLS). The database number (0-15) is optional and defaults to 0.

    **FTP/SFTP** requires a URL in the format `sftp://<<host>>:<<port>>` with `username` and `password` credentials.
  </Accordion>

  <Accordion title="Custom authentication" icon="code">
    For systems with unique authentication requirements, superglue supports multiple custom patterns.

    <Tabs>
      <Tab title="Basic Auth">
        ```typescript theme={null}
        credentials: {
          username: "your_username",
          password: "your_password"
        }
        ```

        Used by: Jenkins, Artifactory, legacy APIs
      </Tab>

      <Tab title="Custom Headers">
        ```typescript theme={null}
        credentials: {
          "X-Custom-Auth": "your_auth_token",
          "X-API-Version": "v2",
          "X-Tenant-ID": "tenant_123"
        }
        ```

        Used by: Internal APIs, multi-tenant systems
      </Tab>

      <Tab title="JWT/Bearer Tokens">
        ```typescript theme={null}
        credentials: {
          bearerToken: "eyJhbGciOiJIUzI1NiIs..."
        }
        ```

        Used by: GitHub (personal access tokens), GitLab, custom auth systems
      </Tab>

      <Tab title="Bot Token">
        ```typescript theme={null}
        credentials: {
          botToken: "xoxb-XXXXXX"
        }
        ```

        Used by: Slack and Discord
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

<Card title="Security first" icon="shield">
  All secrets are encrypted at rest and in transit. The LLM never accesses
  real credentials - only placeholders such as `<<stripe_api_key>>` are exposed during
  workflow setup and execution.
</Card>

<Card title="Not ready to provide credentials?" icon="watch">
  Systems can be created without credentials and updated later. Credentials may also be supplied
  dynamically during tool execution.
</Card>

<Card title="Need help identifying credentials?" icon="user-message">
  The agent can assist with figuring out which credentials are required and where to find them.
  e.g., *"I want to connect to my company’s internal API but I'm not sure what authentication it
  uses."*
</Card>

## Automatic documentation crawling

superglue automatically crawls and processes documentation upon system creation. This makes it possible for superglue to reason about endpoints, authentication, and data models without manual setup.

When creating a system, the **`documentationUrl`** or uploaded documentation files (like OpenAPI specs, PDFs, or HTML exports) are used as the primary source for this process. The more complete and accurate the provided material, the better superglue’s internal understanding of the system.

### Supported documentation formats

superglue’s fetchers handle most modern and legacy documentation types:

<CardGroup cols={2}>
  <Card title="OpenAPI/Swagger" icon="file-code">
    Extracts endpoints, parameters, and schemas from `.json` or `.yaml` specifications.
  </Card>

  <Card title="Mintlify & modern docs" icon="book-open">
    Fetches content from popular hosted sites like Mintlify, ReadMe, or Docusaurus.
  </Card>

  <Card title="Static HTML & PDFs" icon="file-lines">
    Parses legacy or self-hosted documentation, including HTML exports and PDF manuals.
  </Card>

  <Card title="Database schemas" icon="database">
    Automatically analyzes PostgreSQL and MSSQL schemas to identify tables, columns, and
    relationships.
  </Card>
</CardGroup>

### Documentation filtering with keywords

Large APIs can have hundreds of endpoints. To improve accuracy and reduce processing time, you can provide specific keywords via the agent that describe what parts of the documentation are most relevant.

The agent automatically adjusts documentation processing based on your instructions:

```
Connect to Stripe and focus on customer and subscription endpoints
```

This ensures that only relevant documentation is processed and saved to the system. Keywords are used to:

* Guide crawling and processing to retain only the most relevant documentation sections
* Improve ranking and retrieval relevance at runtime

## Development and production environments

<Info>
  **Enterprise Feature** — Multi-environment systems are available on superglue Enterprise plans.
</Info>

Systems can be configured with separate development and production environments. This allows you to test integrations with sandbox/staging credentials before deploying to production.

### How it works

* Each system can have a **dev** and **prod** version with the same ID but different credentials
* When running tools, specify `mode: "dev"` or `mode: "prod"` to control which system credentials are used
* Systems without a linked environment work in both modes (standalone systems)

### Creating environment-specific systems

<Tabs>
  <Tab title="Via UI">
    1. Create your production system as normal
    2. Open the system and click **Add Development Environment**
    3. Configure development-specific credentials (e.g., sandbox API keys)
    4. Both environments share the same documentation and configuration, only credentials differ
  </Tab>

  <Tab title="Via API">
    ```bash theme={null}
    # Create production system
    curl -X POST https://api.superglue.ai/v1/systems \
      -H "Authorization: Bearer $API_KEY" \
      -d '{
        "id": "stripe",
        "name": "Stripe",
        "url": "https://api.stripe.com",
        "environment": "prod",
        "credentials": { "apiKey": "sk_live_..." }
      }'

    # Create linked development system
    curl -X POST https://api.superglue.ai/v1/systems \
      -H "Authorization: Bearer $API_KEY" \
      -d '{
        "id": "stripe",
        "name": "Stripe",
        "url": "https://api.stripe.com",
        "environment": "dev",
        "credentials": { "apiKey": "sk_test_..." }
      }'
    ```
  </Tab>
</Tabs>

### Running tools in different modes

```typescript theme={null}
import { runTool } from "@superglue/client";

// Use production credentials (default)
await runTool("my-tool", {
  inputs: { ... },
  options: { mode: "prod" }
});

// Use development/sandbox credentials
await runTool("my-tool", {
  inputs: { ... },
  options: { mode: "dev" }
});
```

### Environment resolution

When a tool runs with a specific mode:

1. **Linked systems**: If a system has both dev and prod versions, the matching environment is used
2. **Standalone systems**: Systems without a linked counterpart work in both modes
3. **Default**: If no mode is specified, `prod` is used

## IP whitelisting

If your system requires IP whitelisting (firewall rules, security groups, etc.), superglue's outbound IPs are `34.234.12.178` and `18.198.191.215`. Add both to your allowlist.

## Next steps

<Card title="Ready to create your first system?" icon="plug" href="https://app.superglue.cloud">
  Go to superglue and start connecting your APIs, databases, and systems in minutes.
</Card>