A tool endpoint is a public URL that returns your data. Three rules keep it safe:
- Verify the signature on every call, so only ModelRiver can call it.
- Authorize from
end_user, never from the arguments. Your backend sentend_user; the model wrote the arguments. - Return only what that user may see. Anything you return can end up in the answer.
Verify the signature
Every call carries a signature made with your project's tool signing secret:
1signed_string = "v2." + <x-modelriver-timestamp> + "." + <x-modelriver-tool-call-id> + "." + <raw request body>2signature = hex(HMAC-SHA256(key = your tool signing secret, message = signed_string))3header = x-modelriver-signature: v2=<signature>To verify a call:
- Read the body as raw bytes, before any JSON parsing. The signature covers the exact bytes sent; parsing and re-encoding the JSON changes them.
- Reject the call if
x-modelriver-timestampis more than 5 minutes from your clock. - Compute the signature and compare it, in constant time, with each
v2=value inx-modelriver-signature. Accept if any matches.
The header can hold two comma-separated values while a secret is being rotated (see below).
Node.js
1import crypto from 'node:crypto';2 3export function verifyToolCall(rawBody, headers, secrets, toleranceSeconds = 300) {4 const timestamp = headers['x-modelriver-timestamp'];5 const callId = headers['x-modelriver-tool-call-id'];6 const signatures = String(headers['x-modelriver-signature'] || '')7 .split(',')8 .map((part) => part.trim())9 .filter((part) => part.startsWith('v2='))10 .map((part) => part.slice(3));11 12 if (!/^\d+$/.test(timestamp || '') || !callId || signatures.length === 0) return false;13 if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;14 15 return secrets.some((secret) => {16 const expected = crypto17 .createHmac('sha256', secret)18 .update(`v2.${timestamp}.${callId}.`)19 .update(rawBody)20 .digest('hex');21 const expectedBytes = Buffer.from(expected);22 23 return signatures.some((given) => {24 const givenBytes = Buffer.from(given);25 return givenBytes.length === expectedBytes.length && crypto.timingSafeEqual(givenBytes, expectedBytes);26 });27 });28}rawBody is a Buffer: use express.raw({ type: 'application/json' }) in Express, or await request.arrayBuffer() in a fetch-style handler. secrets is a list, so you can accept two during a rotation.
Python
1import hashlib, hmac, time2 3def verify_tool_call(raw_body: bytes, headers, secrets, tolerance_seconds: int = 300) -> bool:4 timestamp = headers.get("x-modelriver-timestamp", "")5 call_id = headers.get("x-modelriver-tool-call-id", "")6 signatures = [7 part.strip()[3:]8 for part in headers.get("x-modelriver-signature", "").split(",")9 if part.strip().startswith("v2=")10 ]11 12 if not timestamp.isdigit() or not call_id or not signatures:13 return False14 if abs(time.time() - int(timestamp)) > tolerance_seconds:15 return False16 17 signed = f"v2.{timestamp}.{call_id}.".encode() + raw_body18 for secret in secrets:19 expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()20 if any(hmac.compare_digest(expected, given) for given in signatures):21 return True22 return FalseA value to test against
1secret mrtool_test_4f9a2c7d1e8b3a6f5c0d9e2b7a1f4c8d2timestamp 17945906233call id tc_3f2a9c1d5b7e4a6f8c0d1e2b4body {"version":2,"type":"tool.call","id":"tc_3f2a9c1d5b7e4a6f8c0d1e2b","tool":"get_sales_summary","arguments":{"period":"this_week"},"end_user":{"id":"user_812","claims":{"plan":"pro"}},"request":{"id":null,"channel_id":"0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b","workflow":"sales_chat","revision_id":"rev_12","round":1,"attempt":1,"mode":"live"}}5signature 5ee0bc5f7ae14a7264dc8f03ccd69713902119d079910a7bee871034cf59f528Your function should produce that signature for that body, with no trailing newline. The secret here is made up for the example; real ones start with mrts_. To check a real call end to end, use Send test call and see whether your endpoint accepts it.
This is not the webhook signature
Webhook deliveries use a different secret and a different scheme: they sign the timestamp and the data value, and send the signature as bare hex. Tool calls sign the whole raw body together with the call id, and prefix the signature with v2=. A webhook verifier will reject tool calls, and the other way round. Keep the two secrets apart.
Stop repeats
A valid call to a tool that reads can be sent twice: ModelRiver retries it once after a 5xx or a dropped connection, with the same x-modelriver-tool-call-id. For tools that only read, answering twice is harmless. A call to a tool that changes something is never retried.
If a call must not be handled twice, remember each call id for a few minutes and answer a repeat with the result you already produced. The 5-minute timestamp check bounds how long you need to remember them.
Authorize from end_user
The model chooses a tool's arguments from the conversation, and the conversation contains text typed by a user. Someone can type "show me the sales for store st_99" and the model may well pass st_99 along.
So the arguments say what is being asked. They never say who is asking:
1// Wrong: the model decides whose data is returned2const summary = await db.salesSummary(call.arguments.store_id, call.arguments.period);3 4// Right: your backend already decided, and ModelRiver signed it5const summary = await db.salesSummary(call.end_user.claims.store_id, call.arguments.period);Leave identifiers that decide access out of the tool's schema altogether. With "additionalProperties": false, a call that includes one anyway is refused before it reaches you.
end_user is what your backend put in the request: check the user's session in your backend, then send their id and the few claims your tools need (a store, a tenant, a role). ModelRiver does not show it to the model, and passes it to your endpoint inside the signed body.
Approvals: what to trust
A tool that changes something runs only after the end user approves the call (see Approvals). The approval is built so that neither the model nor the browser can give it.
- Only your backend decides. Approving and declining need your project API key, so the browser can't do it. Your route must take
end_user.idfrom the signed-in session, never from the browser. ModelRiver accepts the decision only when it equals theend_user.idthe request was sent with (409 end_user_mismatchotherwise), and only for the API key's own project. - The prompt is yours. The approval prompt is text you wrote on the tool, shown as written. Argument values are never put into it, so the model can't write the question.
- The values are the model's. The arguments shown next to the prompt were written by the model, and the conversation can steer it. Show them as plain text, in full, never as HTML, Markdown or links, so a value can't pass for part of your interface.
- Approval is not authorization. The end user saying yes doesn't mean they may do it. Your endpoint still decides from
end_user, as for any call.
What the browser and the webhook see
For a call waiting for approval, the browser (the tool_approval_required event and tool_state), the tool.approval_required webhook and GET /v1/ai/tool-calls/:call_id carry the tool's name, the approval prompt and the values of the arguments ticked under Show to the user. The webhook also carries end_user_id.
Hidden arguments
An argument left unticked under Show to the user never reaches the browser, the webhook or the GET: it is not in the events, tool_state, the webhook, the GET or error bodies. Your endpoint still receives every argument, and Request Logs keep them when the project saves full request and response text. Results never reach the browser or the webhook.
Hiding an argument means the end user approves without seeing it, so the console warns when you untick one. Show everything the end user needs to decide: who an email goes to, which order is cancelled.
Anyone who holds the request's WebSocket token can see a waiting approval and stop the request, but can't approve it.
Prompt injection
A tool result is text the model reads, and your data may contain text someone else wrote: a product review, a support note, a document. That text can try to give the model instructions.
ModelRiver marks every tool result as untrusted data and tells the model that nothing inside one is an instruction. That lowers the risk; it does not remove it. What actually limits the damage is what a tool can do:
- A tool that changes something asks first. Each call runs only after the end user approves it, with the prompt you wrote. A hijacked model can ask, but can't change anything on its own.
- Your endpoint returns only what
end_usermay see, so there is nothing of another user's for the model to leak. - Return fields, not documents, where you can. A number can't carry an instruction.
Rotate the secret
On the Tools tab, under Tool signing secret, select Rotate, then Rotate secret to confirm. The new secret is shown once.
The previous secret keeps working for 24 hours. During that time every call carries two signatures, newest first, and x-modelriver-key-id lists both key ids. To rotate without dropping a call:
- Rotate in the console and copy the new secret.
- Deploy your backend with both secrets in the list it verifies against.
- After 24 hours, remove the old one.
While a rotation is under way you can't rotate again, so the secret your endpoints use is never dropped by accident. To end the 24 hours early, select Finish rotation, tick My endpoints already check the new secret and select Stop the old secret now: the previous secret stops working at once.
If a secret has leaked, rotate and select Finish rotation straight away, so the leaked secret stops working at once, then deploy the new secret. Until it is deployed your endpoints refuse calls, because they are signed only with the new secret.
What goes where
| The model | The end user's browser | Your Request Logs | |
|---|---|---|---|
| Tool names, descriptions, schemas | Yes | Names and progress labels only | Yes |
| Arguments | Yes (it wrote them) | Only for a call waiting for approval: the ones ticked under Show to the user | If the project saves full request and response text |
| Approval prompt | No | Yes, for a call waiting for approval | No. It stays in the workflow's settings |
| Results | Yes | No | If the project saves full request and response text |
error.message from your endpoint | Yes, marked as text from the tool | No | If the project saves full request and response text |
error.user_message | No | Yes | No |
end_user | No | No | As part of the request, if the project saves full request and response text |
| Endpoint URLs | No | No | No. They stay in the workflow's settings |
| The signing secret | No | No | No. Stored encrypted; shown once when created |
Tool call records are deleted together with the request they belong to, on your plan's retention period. So are the approval records of its calls: the prompt, the shown arguments, and the decision.
Test calls and local testing
Two kinds of call don't come from a live request:
- A test call from the console has
"mode": "test"inrequest. Your production endpoint should refuse it unless you expect one, so a test can't act on live data. - A call forwarded by a developer's
modelriver toolssession has"via": "cli"inrequest. It is signed with the same secret, and the whole signed call is handed to whoever runs that session: anyone with one of the project's API keys. The CLI only forwards it to that person's own machine, but the call itself could be replayed for five minutes, so your production endpoint should refuse any call with"via": "cli". The value is inside the signed body, so it can't be removed without breaking the signature.
In the console
- People who can edit a project's workflows can change a saved tool's description, schema, progress label, timeout, approval prompt and the arguments it shows, switch tools on and off, remove tools, change the limits, and duplicate a workflow with its tools.
- Adding a tool, renaming one, changing the address a tool calls, or changing what calling it does is for organization owners and admins: that address receives signed calls with your users'
end_user, and a tool that only reads data runs without asking the end user. - Creating, rotating and finishing the rotation of the signing secret is for organization owners and admins too.
- Send test call is for organization owners and admins, because it sends a signed request to an address typed into the form. It is limited to 20 a minute per person and 300 an hour per organization.
- Creating, rotating and finishing the rotation of the secret, and sending a test call (with the endpoint's host), are recorded in the organization audit log.
Next steps
- Endpoint contract: the full request and response reference
- Approvals: set up a tool that changes something
- Testing: check your verifier against a real signed call