Context Override

Some features — such as AI Security Rules — require additional context to function correctly. This context can be configured in two ways:

• Statically via Security Group Rules
• Dynamically using a URL query parameter, which overrides any statically configured values

Tip

Context override allows you to pass input parameters to the AI evaluator only. This context is not included in the verification data. If you need to pass custom parameters as part of the verification data, see the custom parameters documentation instead.

Related Resources

• AI Security Rules

Encrypting Context

To securely override internal context, the data must be encrypted using a symmetric AES cipher with a shared encryption key.

1. Encode the data as JSON or URL query format.
2. Encrypt the encoded data using the AES-GCM cipher with the CONTEXT_DATA_KEY.
3. Base64 URL-safe encode both the initialization vector (IV) and the encrypted data.
4. Concatenate the IV and encrypted data using a dot (.) as the separator:

base64(iv) + "." + base64(encrypted)

Alternatively, use the POST /v1/context/encrypt endpoint to encrypt the data via the API.

Passing Context Data

To override context data, pass the encrypted payload as a URL query parameter. For example:

/v1/verify?context={ENCRYPTED_CONTEXT_DATA}

The value provided in the URL will override any context previously defined in the Security Group settings.

Example

Below is an example implementation for context override in Ruby:

require 'openssl'
require 'base64'
require 'json'

def encrypt_context(payload, raw_key_string)
  # 1. Prepare the key (ensure it's UTF-8 bytes)
  raw_key = raw_key_string.encode('UTF-8')

  # 2. Setup Cipher
  cipher = OpenSSL::Cipher.new('aes-256-gcm').encrypt
  cipher.key = raw_key

  # 3. Handle the 16-byte IV
  cipher.iv_len = 16
  iv = cipher.random_iv

  # 4. Encrypt
  ciphertext = cipher.update(payload) + cipher.final

  # 5. Get the Auth Tag
  tag = cipher.auth_tag

  # 6. Append Auth Tag to ciphertext
  combined_encrypted_data = ciphertext + tag

  # 7. Encode: base64(iv) + "." + base64(encrypted)
  encoded_iv = Base64.urlsafe_encode64(iv, padding: false)
  encoded_data = Base64.urlsafe_encode64(combined_encrypted_data, padding: false)

  "#{encoded_iv}.#{encoded_data}"
end

# --- Usage ---
# Ensure your key is exactly 32 bytes for aes-256
key = "2b8ecf00dc825052aec2719da1e2aff6"
data = { "hello" => "world" }.to_json

puts encrypt_context(data, key)