Skip to content
Helix Docs

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.

For developers Updated Nov 10, 2026
View as Markdown

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.

Credential fields

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

FieldForm labelRequiredShape
secretsSecretsYesA list of 1 to 50 entries, each with a Name and a Value. The value is masked in the form
templateInjection templateYesText that contains the injection template as JSON. Helix parses it when it applies the authentication
pin_to_domainPin to domainYesThe 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}}:

NameValue
api_keyk-1234
client_secrets-5678
RuleDetail
NameMatches ^[A-Za-z_][A-Za-z0-9_]{0,63}$: a letter or underscore first, then letters, digits, or underscores, up to 64 characters
ValueA non-empty string of well-formed text. A value with a lone surrogate is an error
Count1 to 50 secrets
DuplicatesEach 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
SizeThe whole list is at most 64 KiB (65,536 UTF-8 bytes), measured as the stored JSON array of { "name": ..., "value": ... } objects
Unused secretsAllowed. A secret that no rule references is simply never sent

Template

{
  "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.

KeyTypeDescription
versionnumberMust be the number 1. Any other version is rejected. A future format gets a new version number, and version 1 stays valid
injectarrayOne 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.

PartRule
nameMust be the name of a secret on the authentication. An unknown name is an error
filterOptional. 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 textEverything 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). 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.

{ "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.

KindKeysWrites to
headerin, name, valueA request header
queryin, name, valueA query string parameter
bodyin, name, valueA string field in the request body
cookiein, name, valueOne cookie in the Cookie header
basicin, username, passwordThe Authorization header, as HTTP Basic
pathin, placeholder, valuePlaceholder text in the URL path
{ "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.
    • 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

{ "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.

body

{ "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 bodyWhat happens
JSONAn 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 bodyWith 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-urlencodedA 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 elseAn 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.

{ "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

{ "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:

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

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

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

path

{ "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.

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:

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

Limits

LimitValue
Secrets per authentication50
Secret name length64 characters
Rules in inject1 to 25
Template text size16 KiB (UTF-8 bytes)
Query parameter name length128 characters
Body path depth10 segments
Path placeholder8 to 64 characters: A-Z, 0-9, _, with at least one _
Secrets list size64 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. Read them before you pick the query or path rule or choose a pin.

Loading search…

Jump to a section

tab to move · esc to close