Elements Connect
Elements Connect
Breadcrumbs

Security Restrictions on REST API requests

To protect your REST API data sources and their credentials, Elements Connect restricts where a request can go and what a value inserted into it can change.

Without these restrictions, a user who can edit an issue could steer a request to another endpoint, or a redirect could send your data source credentials to a server you did not configure.

Overview

#

Restriction

Applies to

1

A value cannot be a . or .. path segment

Values inserted in the path

2

FreeMarker cannot turn off escaping

Path and live path templates

3

Control characters in values are encoded

Values inserted in the path

4

A request cannot climb above the API base URL

The whole request URL, including the text you write and redirects

5

No redirect to another host when credentials are sent

Every request to an authenticated data source

Values inserted in the path

Restrictions 1 to 3 apply to every value inserted into the Path or Live path of a connected field, whatever the syntax:

  • FreeMarker expressions: ${issue.summary}, ${userInput}, ${issue.customfield_10022}…

  • Dependencies: $userInput, $issue.customfield_10022, $currentUser…

They do not apply to the text you write yourself in the path (/rest/api/2/search?jql=…). This text is covered by restriction 4 only.

1. Values that are a . or .. path segment

A value that is, or contains, a . or .. path segment is refused. The request is not sent and the field shows the error:

A value inserted into a REST path cannot contain a "." or ".." path segment.

This applies wherever the value is inserted, including in a query parameter.

Value

Result

..

❌ Refused

.

❌ Refused

../admin

❌ Refused

orders/../admin

❌ Refused

%2e%2e (encoded ..)

❌ Refused

v1.2

✅ Allowed

report.json

✅ Allowed

a..b

✅ Allowed

Example

Path: /orders/${issue.customfield_10022}

  • Value ACME-123 → calls /orders/ACME-123

  • Value ../admin → the request is refused

2. Turning off escaping in a FreeMarker path

In a REST path, FreeMarker templates can’t turn off the escaping of inserted values. The following are refused:

  • the ?no_esc built-in, for example ${userInput?no_esc}

  • the <#noautoesc> directive

  • changing the output format, for example with <#outputformat>

The template is refused as soon as it is read: no request is sent, and the field shows an error such as:

Disabling auto-escaping or changing the output format is not allowed in a REST path (line 1, column 20): interpolated values must stay URL-encoded.

What to do: remove ?no_esc, <#noautoesc> or <#outputformat> from your path and live path.

3. Line breaks and other control characters in a value

Line breaks, tabs and other control characters in an inserted value are always URL-encoded (for example, a line break is sent as %0A). A value can no longer split the request in two.

This does not produce an error. If your API expected these characters unencoded, check that it still returns the right data.

The whole request

Restrictions 4 and 5 apply to the full request, not only to inserted values.

4. A request that climbs above the API base URL

The full request URL, made of the data source's API base URL followed by the field's path, must stay under the API base URL. A request whose path climbs above it with .. segments is refused and is not sent.

This applies to:

  • the text you write yourself in the path,

  • the path used to test a connected item,

  • redirects: a redirect whose Location climbs above the API base URL with .. segments is refused too.

The configuration tester shows Invalid URL, and the error says:

URL not allowed for security reason: the path escapes the datasource base URL: https://api.example.com/admin

Example

API base URL: https://api.example.com/rest/v2

Path

Result

/orders/123

✅ Allowed

/orders/../customers

✅ Allowed (stays under /rest/v2)

/../v1/orders

❌ Refused

/../../admin

❌ Refused

/%2e%2e/v1/orders (encoded ..)

❌ Refused

A redirect to another path on the same host that does not use .. segments is still followed.

What to do: if a field needs an endpoint above the API base URL, shorten the API base URL so that it covers every endpoint your fields call (for example https://api.example.com/rest instead of https://api.example.com/rest/v2), then update the field paths to match (/v2/orders/123).

5. Redirects to another host on an authenticated data source

When a REST API data source sends credentials, Elements Connect does not follow a redirect to a different host. The request is refused, so your credentials are never sent to a server you did not configure.

The configuration tester shows Invalid URL.

Data source authentication

Redirect to another host

Basic

❌ Refused

API key, sent in a header

❌ Refused

OAuth 2

❌ Refused

Any authentication with custom headers

❌ Refused

API key, sent as a query parameter

✅ Followed (the key is not forwarded)

No authentication and no custom headers

✅ Followed

A redirect to the same host, even on another port or path, is still followed with the credentials (within the limit of restriction 4).

Example

API base URL: https://api.example.com, Basic authentication

  • https://api.example.com/orders redirects to https://api.example.com/v2/orders → followed

  • https://api.example.com/orders redirects to https://eu.example-cdn.com/orders → refused

What to do: set the API base URL to the host the API finally answers from (here https://eu.example-cdn.com), so that no cross-host redirect is needed.

Other protections

These protections apply to every REST API request:

  • Only HTTPS is accepted.

  • A redirect from HTTPS to HTTP is refused.

  • Private and internal network addresses cannot be called.

  • The number of redirects is limited.

  • The size of the response is limited.

  • The SSL certificate of the API is always checked. Custom certificates cannot be provided.