Accessing secrets in scripting
When writing scripts, you often need to include sensitive values—like authorization tokens or client credentials—in your API calls.
Instead of hard‑coding them, you can use secrets stored at the research domain level. These secrets are securely managed in Rival and inserted into your script with Handlebars syntax.
Secrets are stored as secret key pairs with a secret label and a secret key. To access them in your script, use the Handlebars notation:
{{{secrets.secret_label}}}
Example
You can use a secret in headers, payloads, or anywhere your script needs it.
Here’s an example of adding an Authorization header using a stored secret:
options['Authorization'] = '{{{secrets.authorization}}}'
However, this handlebar is not a general-purpose variable replacement—it only works within certain web service functions.Where the {{{secrets.secret_label}}} handlebar works the secret value is only replaced at runtime when it is used inside these web service functions:
getHttp(domain, options) postHttp(domain, payload, options)
That means:
The secret placeholder will stay as
{{{secrets.secret_label}}}until your script actually calls one of these functions.The Rival system replaces the placeholder with the real secret value inside the HTTP request being sent to the external service.
Example (Correct Usage)
const response = postHttp( 'https://api.example.com/v1/send', { to: user.phone, message: 'Hello!', }, { headers: { Authorization: 'Bearer {{{secrets.EXAMPLE_API_KEY}}}', }, } )In this example:
The secret
EXAMPLE_API_KEYis stored securely in Rival.When
postHttpruns, the system automatically injects the real key into the header.The value is never exposed in logs or stored in the script.
Important Limitations
The {{{secrets.secret_label}}} handlebar does not work everywhere in your script.
If you reference it outside of
getHttp()orpostHttp(), it will not be replaced with the actual secret value.For example, this will not work:
// ❌ Wrong: Value will not be replaced const apiKey = '{{{secrets.EXAMPLE_API_KEY}}}'; log(apiKey); // prints "{{{secrets.EXAMPLE_API_KEY}}}" (not the real key)This happens because secrets are designed to be resolved only inside HTTP requests, to prevent accidental exposure or misuse.
This retrieves the secret stored under the secret label and injects it at runtime. Your script will never expose the actual value in logs or UI—it is handled securely.
getHttp(domain, options)
Sends an HTTP GET request to an external API endpoint to retrieve data. This function can be used in chat flows or background scripts to make decisions based on external data. The request is executed only if the target endpoint is registered as a whitelisted domain.
Argument | Required | Description |
domain | ✔️ | Full URL of the whitelisted endpoint, including query parameters e.g. |
options | ✔️ | Key-value pairs for HTTP request headers e.g. |
Returns a JSON response with the following structure:
{
data: {}, // response data from the API
statusCode: 200 // HTTP status code (e.g., 200, 404, 500)
}
The getHttp method often requires use of secret keys (e.g., API tokens, credentials) which must not be hardcoded or exposed directly in the script. To enhance security:
Store secrets in the Research Domain → Secret Key Pair page.
Use Handlebars annotations to reference secrets safely within the script.
Example using getHttp
local whitelistedEndpoint = 'https://api.bhn.com/user?user_id=123'
local options = {}
options['Authorization'] = '{{{secrets.authorization}}}'
options['Content-Type'] = 'application/json'
local result = getHttp(whitelistedEndpoint, options)
return result.data
postHttp(domain, payload, options)
Sends an HTTP POST request to an external API endpoint with a custom payload and headers. The request is executed only if the target endpoint is registered as a whitelisted domain.
Argument | Required | Description |
domain | ✔️ | Full URL of the whitelisted endpoint e.g. |
payload | ✔️ | A JSON object containing the body of the POST request, structured as key-value pairs. |
options | ✔️ | Key-value pairs for HTTP request headers e.g. |
Returns a JSON response with the following structure:
{
data: {
message: 'The request has completed successfully',
data: {
pointBalance: 534
}
},
statusCode: 200 // HTTP status code (e.g., 200, 404, 500)
}
Just like with getHttp, the postHttp method may require secret keys (such as API tokens), which should never be hardcoded—these should be stored in the Research Domain’s Secret Key Pair page and securely referenced using Handlebars (e.g., {{secrets.my_api_token}}).
Example using postHttp
local whitelistedEndpoint = 'https://api.rybbon.net/v2/points'
local payload = {}
local options = {}
payload['client_id'] = '{{{secrets.clientId}}}'
payload['client_secret'] = '{{{secrets.clientSecret}}}'
payload['points'] = 381
payload['email_address'] = 'example123@rivaltech.com'
payload['participant_id'] = 'ed095041-7414-4ad3-8b02-a503fac42a4c'
options['Authorization'] = '{{{secrets.authorization}}}'
options['Content-Type'] = 'application/json'
local result = postHttp(whitelistedEndpoint, payload, options)
return result.data
encodeJSON(object)
Converts a Lua object into a JSON string representation.
Argument | Required | Description |
| ✔️ | A Lua object to be converted to JSON |
Returns |
A JSON string representation of the object. |
Example
local data = {}
data["name"] = "Alice"
data["age"] = 25
local jsonString = encodeJSON(data)
return jsonString -- returns '{"name":"Alice","age":25}'
local obj = {
name = "John",
age = 30,
items = {"item1", "item2"}
}
local json_str = cjson.encode(obj)
print(json_str) -- '{"name":"John","age":30,"items":["item1","item2"]}'
decodeJSON(jsonString)
Parses a JSON string and converts it into a Lua object that can be manipulated within the script.
Argument | Required | Description |
| ✔️ | A valid JSON string to be parsed into a object |
Returns |
A Lua object representing the parsed JSON data. Returns null if the JSON string is invalid. |
Example
local payload = decodeJSON('{"name":"Bob","age":30}')
log(payload.name) -- returns "Bob"
log(payload.age) -- returns 30
Combined Example
local payload = decodeJSON('{"name":"Bob","age":30}')
payload["name"] = "Alice"
local result = encodeJSON(payload)
return result -- returns '{"name":"Alice","age":30}'