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}}}'
This retrieves the secret stored under the label authorization 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}'
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}'