> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/reference-manual/v3.44.2/advanced-topics/gateway-based-imports.md).

# Gateway-based imports

Elimity Insights v3.42.0 introduced a new feature for importing data into custom sources. More specifically, it aims to avoid the out-of-band configuration management and scheduling necessary for agent-based imports. The following table compares several aspects of both agent- and gateway-based imports:

<table data-full-width="true"><thead><tr><th></th><th>Agent-based</th><th>Gateway-based</th></tr></thead><tbody><tr><td><strong>Traffic direction</strong></td><td>Agent pushes to Elimity Insights' API</td><td>Elimity Insights pulls from gateway's API</td></tr><tr><td><strong>Authentication with Elimity Insights</strong></td><td>Connector admin generates API credentials in Elimity Insights and places them in out-of-band configuration for the agent</td><td>Connector admin configures gateway URL in Elimity Insights, HTTPS by itself already provides the necessary authentication</td></tr><tr><td><strong>Authentication with underlying data source</strong></td><td>Connector admin places credentials in out-of-band configuration for the agent</td><td>Connector admin provides credentials as gateway configuration values in Elimity Insights</td></tr><tr><td><strong>Authentication with gateway</strong></td><td>Not applicable</td><td>Optional and only necessary if underlying data source requires additional protection; refer to <a href="#authenticating-with-gateways">the dedicated section below</a> for additional information</td></tr><tr><td><strong>Scheduling</strong></td><td>Connector admin configures schedule out-of-band</td><td>Connector admin configures CRON schedule in Elimity Insights</td></tr><tr><td><strong>Deployment</strong></td><td>Job in Azure Container Apps, job in Google Cloud Run, ...</td><td>App in Azure Container Apps, service in Google Cloud Run, ...</td></tr><tr><td><strong>Development</strong></td><td>Python or NodeJS script which uses an official client library for pushing to Elimity Insights' API</td><td>HTTP server in Go, NodeJS or Python which uses the official SDK for communication with Elimity Insights</td></tr></tbody></table>

In general we recommend all new customers to use gateway-based imports when possible.

## Authenticating with gateways

In most circumstances authentication for gateway-based imports is already sufficiently covered by the combination of HTTPS and credentials for the underlying data source. However, sometimes additional protection of the gateway's HTTP(S) endpoint is necessary (e.g. if the gateway itself implicitly authenticates to the underlying source). For these use cases, Elimity Insights supports including OAuth2 access tokens in its requests to gateways. More specifically, our on-prem customers can enable this feature with the `EnableGatewayOAuth2` configuration option. For SaaS customers we can provide a fully configured setup upon request. The diagram below depicts the authentication flow in more detail:

<figure><img src="/files/mL5eoH89TbuX7xcQ2FA0" alt=""><figcaption></figcaption></figure>

As you can see, in this case Elimity Insights includes access tokens from our own OAuth2 server at `auth.elimity.com`. More specifically, we'll make sure those tokens adhere to the JWT standard and have the following custom claims:

| Claim         | Value                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `aud`         | `"gateway"`                                                                                                        |
| `base_url`    | Base URL of the Elimity Insights tenant that requested the access token, e.g. `"https://example.elimity.com"`      |
| `gateway_url` | URL of the gateway for which Elimity Insights has requested the access token, e.g. `"https://gateway.example.com"` |
| `iss`         | `"https://auth.elimity.com/"`                                                                                      |
| `source_id`   | Unique identifier of the source for which to import into Elimity Insights, e.g. `"42"`                             |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.elimity.com/reference-manual/v3.44.2/advanced-topics/gateway-based-imports.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.