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

# Proxy API

> Send requests directly to an integration provider, on behalf of Connected Users.

<Info>
  Proxy API was formerly known as the Connect API.
</Info>

## Introduction

Once your users have connected their third-party app accounts in the Connect Portal, you can access their app account via the Proxy API.

The Proxy API allows you to directly access any of the third-party provider's API methods. With the SDK, you can use [`paragon.request`](/apis/api-reference#.request-integrationtype-string-path-string-requestoptions-requestinit-promise-less-than-unknown-gre) to send an API request to a third-party app on behalf of one of your Connected Users.

Along with [Workflows](/workflows/building-workflows), the Proxy API is one of two primary ways to build integrations with Paragon.

## When to use the Proxy API

The Proxy API is the most flexible way to interact with your users' third-party apps, and is a useful code-based approach for situations including:

* Performing a simple one-off request (e.g. fetching a list of Salesforce contacts)
* Accessing API methods that may not be available in Workflow [Integration Actions](/workflows/integration-actions)
* Writing custom code for complex or unique integration use cases
* Migrating existing integration code to Paragon

## Making requests with the Proxy API

Every integration in your dashboard has a code example of using `paragon.request`, which takes the following arguments:

* `integrationType`: The short name for the integration. i.e. "salesforce" or "googleCalendar". You can find this string on the Overview tab of the integration you want to access, on your Paragon dashboard.
  * When using a custom integration, the `integrationType` name is prefixed with `"custom."` For example, a custom integration titled "TaskLab" would be called `"custom.tasklab"`.
* `path`: The path (without the hostname) of the API request you are trying to access. An example might be "/v1/charges" for Stripe's charge API or "chat.postMessage" for Slack's Web API.
* `requestOptions` (optional): Request options to include, such as:

  * `body`: An object representing JSON contents of the request.
  * `method`: An HTTP verb such as "GET" or "POST". Defaults to GET.
  * `headers`: Additional HTTP headers to include in the request.

  If `requestOptions` is omitted, the SDK issues a `GET` request without a body.

The function returns a Promise for the request output, which will have a shape that varies depending on the integration and API endpoint.

### Client-side SDK Usage

```js JavaScript SDK theme={null}
await paragon.request('slack', '/chat.postMessage', {
	method: 'POST',
	body: {
		channel: 'CXXXXXXX0' // Channel ID,
		text: 'This message was sent with Paragon Connect :exploding_head:'
	}
});

// -> Responds with { ok: true }, and sends a Slack message :)
```

### Server-side Usage

**Base URL:**

* Cloud: `https://proxy.useparagon.com`
* [On-premise environments](/on-premise/hosting-paragon-on-premise): `https://worker-proxy.`\[your on-prem host name]

If you'd like to issue a request from your server to an integration on behalf of an end-user, you can make a request to one of the following paths:

* `/projects/<Project ID>/sdk/proxy/<Integration Type>/<API Path>`
* or `/projects/<Project ID>/sdk/proxy/custom/<Integration ID>/<API Path>` for [Custom Integrations](/resources/custom-integrations).

<Tabs>
  <Tab title="REST API">
    ```bash theme={null}
    https://proxy.useparagon.com/projects/<Paragon Project ID>/sdk/proxy
      /<Integration name>/<API path>

    Authorization: Bearer <Paragon User Token>
    ```

    * A Bearer token must also be specified with a Paragon User Token.

    * This endpoint accepts any HTTP verb you want to use with the API.

    * Body contents must be specified as `application/json`.

    **Example**:

    ```bash theme={null}
    POST https://proxy.useparagon.com/projects/19d...012/sdk/proxy/slack/chat.postMessage

    Authorization: Bearer eyJ...
    Content-Type: application/json

    { 
        "channel": "CXXXXXXX0", 
        "text": "This message was sent with Paragon Connect :exploding_head:" 
    }
    ```
  </Tab>

  <Tab title="REST API (Custom Integrations)">
    When sending Proxy API requests for Custom Integrations, the request path differs slightly. Use the `/custom/` path to send requests as shown:

    ```bash theme={null}
    https://proxy.useparagon.com/projects/<Paragon Project ID>/sdk/proxy
      /custom/<Integration ID>/<API path>

    Authorization: Bearer <Paragon User Token>
    ```

    * A Bearer token must also be specified with a Paragon User Token.

    * This endpoint accepts any HTTP verb you want to use with the API.

    * The Integration ID can be found in the dashboard (`/.../integrations/<Integration ID>`) or with the [Get project's integrations](/apis/api-reference#get-projects-integrations) API endpoint.

    **Example:**

    ```bash theme={null}
    POST https://proxy.useparagon.com/projects/19d...012/sdk/proxy
        /fb243b75-35e7-46b3-ba6c-967ccebeb449/notifications

    Authorization: Bearer eyJ...
    Content-Type: application/json

    { 
        "title": "This notification was created from your app"
    }
    ```
  </Tab>
</Tabs>

## Requesting files or binary response data

By default, the Proxy API will attempt to parse the response data from the integration API as JSON. To receive the raw response data (including all HTTP headers that were received from the integration API), you can pass the `X-Paragon-Use-Raw-Response` header to the request.

This can be used when downloading binary/file data, such as images or PDF files, where the response cannot be encoded as JSON.

*The JavaScript SDK currently does not support returning non-JSON payloads. As an alternative, you can use your preferred request client to make the below API request.*

Below is an example of using the Proxy API to download a file from Google Drive using their [`files.get`](https://developers.google.com/drive/api/v3/reference/files/get) endpoint.

```curl REST API theme={null}
GET https://proxy.useparagon.com/projects/19d...012/sdk/proxy/googledrive/files/<File ID>/?alt=media

Authorization: Bearer eyJ...
X-Paragon-Use-Raw-Response: 1
```

## Changing the Base URL

In some cases, the Base URL included automatically in the Proxy API isn't the one you want to send requests to.

To change the Base URL of a Proxy request, simply use a fully-qualified URL rather than a relative path:

```bash theme={null}
https://proxy.useparagon.com/projects/[Project ID]/sdk/proxy/googledrive/https://sheets.googleapis.com/v4/spreadsheets
```

In this example, the URL that will be requested is **`https://sheets.googleapis.com/v4/spreadsheets`**.

<Note>
  **Note**: Integrations have a permitted list of hosts that can be reached with the Proxy API. If you get the error "This domain is invalid for the current integration", you may be using an unpermitted host.
</Note>