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.
| 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
{
"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). 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.
| 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
{ "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.
namemust 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, andexpect, and any name that starts withproxy-. 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, andrange, and any name that starts withaccept,content-,if-, orsec-fetch-. This includescontent-type,content-encoding, andcontent-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, andx-request-id(a request ID header), and any name that starts withx-forwarded-orx-b3-. - Method-override headers, because they could change the request method at the API:
x-http-method-override,x-http-method, andx-method-override. - Headers reserved for the platform’s own use. The error names the offending header.
- Connection and framing headers:
- 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 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
{ "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.
namemust 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 thebase64urlfilter, 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.
placeholdermatches^(?=.*_)[A-Z0-9_]{8,64}$: 8 to 64 uppercase letters, digits, and underscores, with at least one underscore, such asBOT_TOKEN. An ordinary path word such asaccountscan 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/getMeworks. 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
encodeURIComponentbefore it is inserted. A secret such as123:abcbecomes123%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%2eand%2Eand 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:
| 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, orpin_to_domainis 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
GETorHEADrequest. - 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.