# Custom JSON auth template reference

> Credential fields, template schema, placeholders, filters, the six rule kinds, conflicts, limits, and errors for the Custom JSON Auth Template service.

The **Custom JSON Auth Template** service (`custom-json-auth-template`, version 1) stores several named secrets together with a JSON template that says where each secret goes in the outbound request: a header, a query parameter, a body field, a cookie, a Basic credential, or a placeholder in the URL path. Use it for an API whose authentication doesn't fit one of the other generic services. This page is the complete specification. For a walkthrough with worked examples, see [connect an API with custom JSON auth](/documentation/guides/custom-json-auth/).

## Credential fields

An authentication for this service holds three fields. You fill them in on a form in the dashboard.

| Field | Form label | Required | Shape |
|---|---|---|---|
| `secrets` | Secrets | Yes | A list of 1 to 50 entries, each with a **Name** and a **Value**. The value is masked in the form |
| `template` | Injection template | Yes | Text that contains the injection template as JSON. Helix parses it when it applies the authentication |
| `pin_to_domain` | Pin to domain | Yes | The bare domain this authentication may be used with. A request whose host is that domain, or a subdomain of it, is allowed. Any other host fails. Enter the domain only: no `https://`, path, wildcard, or port. It must have at least two labels (letters, digits, and hyphens), not end in an all-digit label, not look like an IP address, and not be a bare top-level domain or a common public suffix such as `co.uk` or `com.au`. The suffix check uses a short list, so a broad domain such as `amazonaws.com` is accepted: pin as narrowly as the API allows |

### Secrets

Each entry in the **Secrets** list has a name and a value. The template refers to a secret by its name, so with these entries a template can use `{{api_key}}` and `{{client_secret}}`:

| Name | Value |
|---|---|
| `api_key` | `k-1234` |
| `client_secret` | `s-5678` |

| Rule | Detail |
|---|---|
| Name | Matches `^[A-Za-z_][A-Za-z0-9_]{0,63}$`: a letter or underscore first, then letters, digits, or underscores, up to 64 characters |
| Value | A non-empty string of well-formed text. A value with a lone surrogate is an error |
| Count | 1 to 50 secrets |
| Duplicates | Each name must be unique. Names are case-sensitive, so `api_key` and `API_KEY` are two secrets. A name used twice is an error when the authentication is applied |
| Size | The whole list is at most 64 KiB (65,536 UTF-8 bytes), measured as the stored JSON array of `{ "name": ..., "value": ... }` objects |
| Unused secrets | Allowed. A secret that no rule references is simply never sent |

## Template

```json
{
  "version": 1,
  "inject": [
    { "in": "header", "name": "X-Api-Key", "value": "{{api_key}}" },
    { "in": "header", "name": "X-Auth-Token", "value": "{{token}}" },
    { "in": "query", "name": "key", "value": "{{api_key}}" },
    { "in": "body", "name": "auth.client_secret", "value": "{{client_secret}}" },
    { "in": "cookie", "name": "session", "value": "{{session_id}}" },
    { "in": "basic", "username": "{{user}}", "password": "{{pass}}" },
    { "in": "path", "placeholder": "BOT_TOKEN", "value": "{{bot_token}}" }
  ]
}
```

The example shows every rule kind once. A real template uses only the rules the API needs.

| Key | Type | Description |
|---|---|---|
| `version` | number | Must be the number `1`. Any other version is rejected. A future format gets a new version number, and version 1 stays valid |
| `inject` | array | One to 25 rules, each an object with an `in` key that names its kind |

The template is strict. A key that isn't listed on this page is rejected, at the top level and inside every rule. The template text can be at most 16 KiB (16,384 UTF-8 bytes), measured as written. It must parse as one JSON object.

## Placeholders and filters

The `value` of a header, query, body, cookie, or path rule, and the `username` and `password` of a Basic rule, are strings that can contain placeholders. A placeholder is `{{ name }}` or `{{ name | filter }}`. Whitespace inside the braces is allowed, so `{{api_key}}` and `{{ api_key }}` are the same.

| Part | Rule |
|---|---|
| `name` | Must be the name of a secret on the authentication. An unknown name is an error |
| `filter` | Optional. One of `base64` or `base64url`, which encode that one secret's UTF-8 value. `base64` keeps the `=` padding, and `base64url` uses the URL-safe alphabet and drops the padding. No other filter is supported, and an unknown filter is an error |
| Literal text | Everything outside the braces is sent as written. There is no escape syntax in version 1, so a literal `{{` can't appear in a value |

A value field must contain at least one placeholder. A rule made only of literal text is rejected, because the template injects secrets and doesn't rewrite requests. For a Basic rule, at least one of `username` and `password` must contain a placeholder, and the other can be literal text (see [basic](#basic)). A placeholder that is never closed, such as `{{ api_key`, is an error. The literal text around the placeholders must be well-formed too: text with a lone surrogate (half of a Unicode surrogate pair) is rejected with an error that says the field "contains malformed text".

Rendering happens in a single pass. If a secret's value contains `{{x}}`, those characters are sent as they are and are not expanded again.

```json
{ "in": "header", "name": "Authorization", "value": "Bearer {{ token | base64url }}" }
```

## Rule kinds

All rules are strict: a key that isn't listed for the kind is rejected.

| Kind | Keys | Writes to |
|---|---|---|
| `header` | `in`, `name`, `value` | A request header |
| `query` | `in`, `name`, `value` | A query string parameter |
| `body` | `in`, `name`, `value` | A string field in the request body |
| `cookie` | `in`, `name`, `value` | One cookie in the `Cookie` header |
| `basic` | `in`, `username`, `password` | The `Authorization` header, as HTTP Basic |
| `path` | `in`, `placeholder`, `value` | Placeholder text in the URL path |

### header

```json
{ "in": "header", "name": "X-Api-Key", "value": "{{api_key}}" }
```

Sets the header and replaces every header of the same name that your code supplied. Names are compared without regard to case.

- `name` must be a valid HTTP header name (an RFC 7230 token), and must not be on the denied list below. Names are compared in any letter case. The list is grouped by why the header can't be set:
  - Connection and framing headers: `host`, `content-length`, `transfer-encoding`, `connection`, `keep-alive`, `upgrade`, `te`, `trailer`, and `expect`, and any name that starts with `proxy-`.
  - `cookie`. To set a cookie, use the [cookie rule](#cookie).
  - Headers that Helix records in request logs, so a secret placed there would be logged: `user-agent`, `cache-control`, `origin`, `pragma`, and `range`, and any name that starts with `accept`, `content-`, `if-`, or `sec-fetch-`. This includes `content-type`, `content-encoding`, and `content-language`.
  - Forwarding and tracing headers that Helix removes before the request leaves, so a secret placed there would never reach the API: `forwarded`, `via`, `x-real-ip`, `b3`, `traceparent`, `tracestate`, and `x-request-id` (a request ID header), and any name that starts with `x-forwarded-` or `x-b3-`.
  - Method-override headers, because they could change the request method at the API: `x-http-method-override`, `x-http-method`, and `x-method-override`.
  - Headers reserved for the platform's own use. The error names the offending header.
- The rendered value can contain only tab, printable ASCII, and the characters U+0080 to U+00FF. Any other control character (including CR, LF, and NUL), or any character above U+00FF, is rejected. If a secret might contain such characters, encode it with a filter, but only if the API accepts the encoded form.

### query

```json
{ "in": "query", "name": "key", "value": "{{api_key}}" }
```

Sets the query parameter and replaces any parameter of the same name that your code supplied. Names are compared with case, so `Key` and `key` are different parameters. `name` must be non-empty, at most 128 characters, and free of control characters.

This holds whether your code wrote the parameter in the URL string (for example `?key=...`) or passed it in the `query` option of the call: either way the template's value replaces it, and the API receives the parameter once.

The secret ends up in the URL. See the [security notes](/documentation/guides/custom-json-auth/#security-notes).

### body

```json
{ "in": "body", "name": "auth.client_secret", "value": "{{client_secret}}" }
```

Sets a string field in the request body. `name` is a dot path: `auth.client_secret` sets `client_secret` inside the `auth` object. Each segment must be non-empty, can't be `__proto__`, `constructor`, or `prototype`, and the path can be at most 10 segments deep.

The kinds of body that are supported:

| Request body | What happens |
|---|---|
| JSON | An object you pass in `body`, or a string or raw bytes with a JSON content type. The content type can have no charset or `charset=utf-8`. The root must be an object. Missing intermediate objects are created. An existing leaf is overwritten. An existing intermediate that isn't an object is an error |
| No body | With no `Content-Type`, or a JSON one, Helix starts from `{}`, sets the field, and sends the object as JSON, adding `Content-Type: application/json` when you set none. With a form content type, Helix sends a form body that holds just that field. With any other content type, the request is rejected |
| `application/x-www-form-urlencoded` | A string or raw bytes body. `name` is taken literally as a top-level field, so a name with a dot in it is an error for a form body. An existing field of that name is replaced |
| Anything else | An error: multipart, plain text, or JSON with an array at the root |

A body rule on a `GET` or `HEAD` request is an error. A string or raw bytes body with no `Content-Type` is rejected: pass an object, or set the content type.

Helix parses a JSON body and serializes it again, so integers beyond 2^53 lose precision and duplicate keys collapse into one. A form body is parsed and re-encoded as UTF-8: a standard decoder reads the same fields, but the bytes are not identical to what you sent. A form content type must have no `charset` or `charset=utf-8`, and the body must be valid UTF-8; anything else is rejected. If the API depends on the exact bytes of the body, don't use a body rule.

### cookie

```json
{ "in": "cookie", "name": "session", "value": "{{session_id}}" }
```

Adds `name=value` to the `Cookie` header, joined to any cookies your code sent with `; `. A cookie of the same name that your code sent is replaced.

- `name` must be a valid cookie name (an RFC 7230 token).
- The rendered value can contain only RFC 6265 cookie characters. Whitespace, `"`, `,`, `;`, `\`, and control characters are rejected. If a secret might contain them, encode it with the `base64url` filter, but only if the API accepts the encoded form.

### basic

```json
{ "in": "basic", "username": "{{user}}", "password": "{{pass}}" }
```

Sends `Authorization: Basic <base64 of username:password>` and replaces any `Authorization` header your code supplied. The rendered username can't contain `:`, and `username` can't be empty. The username can be literal text or a placeholder. The password can also be literal text, including an empty string. At least one of the two must contain a placeholder:

```json
{ "in": "basic", "username": "api", "password": "{{api_key}}" }
```

An empty literal password suits an API that takes its key as the username:

```json
{ "in": "basic", "username": "{{api_key}}", "password": "" }
```

### path

```json
{ "in": "path", "placeholder": "BOT_TOKEN", "value": "{{bot_token}}" }
```

For an API that carries the secret in the URL path, such as `https://api.example.com/botBOT_TOKEN/getMe`. Your code puts the placeholder text in the URL, and Helix replaces it before sending.

- `placeholder` matches `^(?=.*_)[A-Z0-9_]{8,64}$`: 8 to 64 uppercase letters, digits, and underscores, with at least one underscore, such as `BOT_TOKEN`. An ordinary path word such as `accounts` can never be a placeholder.
- Every occurrence of the placeholder text in the path is replaced. The match is exact, including case, and it is a substring match anywhere in the path, so `/botBOT_TOKEN/getMe` works. Choose text that can't occur in a real path.
- The path ends at the first `?` or `#`. Only the path is searched, not the query string or the fragment. A placeholder that appears only after a `?` or `#` counts as not found.
- The rendered value is percent-encoded with `encodeURIComponent` before it is inserted. A secret such as `123:abc` becomes `123%3Aabc`.
- A placeholder that isn't in the request path is an error, not a no-op.
- The result must still be a valid path that starts with a single `/`. If the substitution produces a `.` or `..` path segment, the request is rejected. Dot segments are detected without regard to case and include the percent-encoded forms `%2e` and `%2E` and mixed forms such as `.%2E`. A path you pass that already has a dot segment is also rejected, with its own error, when the template has a path rule.

The secret ends up in the URL. See the [security notes](/documentation/guides/custom-json-auth/#security-notes).

### Host rules are not supported

There is no rule kind for the host. The `pin_to_domain` field alone decides which hosts the authentication can reach, so a template can't redirect a request to another host.

## HTTPS and redirects

Only `https://` URLs are accepted. A request to an `http://` URL is rejected with a 400, never upgraded.

Helix never follows redirects. A 3xx answer is returned to your code as it is, so an injected credential never follows a redirect. If your code follows it, that is a new request: the credential is injected and the host is checked against the pin again.

## Conflicts

A template is rejected when two rules write to the same place:

| Conflict | Example |
|---|---|
| Two rules for the same header, ignoring case. A `basic` rule counts as the `authorization` header | `X-Api-Key` and `x-api-key`; `basic` and a header rule named `Authorization` |
| Two query rules with the same name | `key` and `key` |
| Two cookie rules with the same name | `session` and `session` |
| Two path rules with the same placeholder | `BOT_TOKEN` and `BOT_TOKEN` |
| Two body rules where one path is the other, or a parent of it. Paths are compared segment by segment | `auth` and `auth.secret`; `a.b` and `a.b`. Not a conflict: `a.b` and `a.bc` |

## Limits

| Limit | Value |
|---|---|
| Secrets per authentication | 50 |
| Secret name length | 64 characters |
| Rules in `inject` | 1 to 25 |
| Template text size | 16 KiB (UTF-8 bytes) |
| Query parameter name length | 128 characters |
| Body path depth | 10 segments |
| Path placeholder | 8 to 64 characters: `A-Z`, `0-9`, `_`, with at least one `_` |
| Secrets list size | 64 KiB (UTF-8 bytes) |

## Errors

Every template or rendering error is detected before the request is sent. If anything is wrong, the API receives nothing. Helix checks the whole template and renders every value before it changes the request, so a failure never leaves a half-applied credential.

Your function sees a rejected request as a thrown error, not a returned response. `ctx.http.authed(alias)` throws an `SdkError` whose `detail.status` is 400 and whose `detail.code` is `invalid_authenticated_request`. A non-2xx answer from the API itself is different: it is returned in `status`, as for any authed call.

The conditions that cause a rejection:

- `secrets`, `template`, or `pin_to_domain` is missing or invalid (for example, two secrets with the same name, or a pin that is an IP address or a public suffix), or the template text isn't valid JSON.
- The template breaks a rule in this reference: an unknown key, a wrong `version`, a limit exceeded, or a conflict.
- A placeholder names a secret that isn't on the authentication.
- A value has no placeholder, or its literal text contains malformed text (a lone surrogate).
- A rendered value is not allowed in its place, such as a header value with a line break, a cookie value with a `;`, or a path value that produces a `.` or `..` segment.
- A header rule names a denied header, including a method-override header.
- The path you pass has a `.` or `..` segment (in any case or percent-encoded form) while the template has a path rule.
- A body rule meets a body it can't edit, or a `GET` or `HEAD` request.
- A path placeholder isn't in the request path, including when it appears only in the query string or after a `#`.
- The URL starts with `http://`.
- The request host is outside the pinned domain.

The error message starts with "custom JSON authentication", names the specific problem (such as an unknown filter or an unclosed placeholder), names the field, the rule's position in `inject`, or the secret's name, and says what to fix. It never contains a secret value or a rendered value. When you debug a failure, the message tells you which rule or secret to look at, not what was in it.

## Security notes

The domain pin, HTTPS-only requests, the redirect rule, and the risk that an API echoes a secret back are covered in the guide's [security notes](/documentation/guides/custom-json-auth/#security-notes). Read them before you pick the `query` or `path` rule or choose a pin.

---

Canonical: https://helix.tray.ai/documentation/reference/custom-json-auth-template/
Any link on this page is available as markdown by appending .md to its URL.
Full corpus: https://helix.tray.ai/documentation/llms-full.txt