Tool security and deployment

The framework handler verifies signed discovery and invocation requests. Configure FLEXKIT_TOOLS_SECRET server-side; 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.

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.

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.