Create Handoff Connection
Create a handoff connection for the caller’s organization.
Credentials go in through api.save_handoff_connection — the api
view has no writable auth_details column at all — and the row is read back
through the view, so what comes out has never carried the token.
Headers
Organization ID for user PATs (pat_ prefix tokens)
Body
Body for POST /handoff/connections.
Human-readable label for this connection
Provider credentials — write-only, never returned
Handoff provider. Only 'gladly' is supported today.
Shared secret used to verify inbound webhook signatures
How this helpdesk behaves — SLA timers and what context it is sent. Shared by every agent that escalates through this connection.
Response
Successful Response
A handoff connection as any caller is allowed to see it.
Explicitly modelled rather than returning the entity, so no future field added to
HandoffConnection can leak a credential by default. auth_details here is
the {base_url, username} pair only.
How this helpdesk behaves — as opposed to how to reach it.
These sit on the connection rather than on an escalation rule because they describe the HELPDESK, not the route: how fast that team answers and what context it wants to receive. Change one here and every agent routing through this connection follows, which is the point — an SLA is not a per-agent setting.
Customer-facing copy deliberately does NOT live here. It is spoken in the agent's voice and language, and one connection is shared by every agent in the org, so a shared waiting message would put the wrong language in front of somebody. That stays on the rule.

