Tool security and deployment

The tools handler verifies signed discovery and invocation requests. Configure FLEXKIT_TOOLS_SECRET server-side (or pass secret to createToolsHandler); the handler refuses tool requests when no secret is configured.

Authorization belongs in the tool

A valid signature establishes the invocation source. It does not decide which business actions your tool should permit. Validate the actor and authorize access to each external system or record before performing a side effect.

Chat actors carry userId, role, and spaceCodes. Automation actors carry automationId, spaceId, and spaceCodes. Branch on actor.kind; an automation actor does not have a Chat user’s identity fields.

GraphQL approval policy is not a general transaction boundary around custom code. Design external writes with their own authority, confirmation where required, and duplicate handling. Return only data that the caller is permitted to receive.

Local runtimes

A connected flexkit dev receives the same actor payloads as production and runs with the developer’s local environment variables. Only the developer who started it is routed to it, and only for Chat turns and manual runs made from a signed-in session; API tokens and background triggers always use the production URL. Treat a local runtime as a developer convenience, not as a deployment target.

Deployment and rotation

Deploy the code and server secret together, then sync the catalog and test a harmless invocation. The handler accepts FLEXKIT_TOOLS_SECRET_PREVIOUS during a coordinated rotation. Update the Dashboard and deployed environment consistently, verify discovery/invocation, and remove the previous secret after the transition. Running flexkit tools sync after each deploy keeps the catalog aligned with the code.

Signed requests include a timestamp and bind method, path, and body. Proxies that rewrite the signed path or alter the body can cause verification failures. Keep server clocks correct.

Failure handling

Do not expose credentials in thrown error messages. Use timeouts for outbound requests and design repeatable operations so a repeated invocation cannot silently duplicate a charge or message. Inspect actual side effects before retrying a failed run.