Agent sessions
Share an agent chat URL with a teammate, customer, or background service.
Agent sessions
A session is one user's conversation with an agent. To let someone chat with an agent you don't own — and don't want to hand credentials to — mint a session ticket and hand them a URL. The ticket is single-use and time-bound.
Agent sessions are one of Wacht's four vanity-page flows; the same /session/tickets endpoint also issues tickets for user impersonation, API-auth management, and webhook management. See Vanity tickets below for the full table.
API flow
wacht api call createBackendSessionTicket --body @ticket.jsonticket.json (minimum for an agent session):
{
"ticket_type": "agent_access",
"agent_ids": ["<agent_id>"],
"actor_id": "<actor_id>"
}Response:
{ "ticket": "<ticket>", "expires_at": <epoch> }URL:
https://<deployment.backend_host>/vanity/agents?ticket=<ticket>backend_host comes from wacht deployments current or getDeploymentWithSettings. Run wacht api describe createBackendSessionTicket for the full request schema.
Useful optional fields:
| Field | Effect |
|---|---|
user_id | Bind the chat to a specific Wacht user; the session authenticates as them. |
actor_id | Bind to a service / non-user actor. |
agent_session_identifier | Resume a specific named session instead of opening a new one. |
expires_in | Seconds until the ticket can no longer be redeemed. |
Pick the narrowest scope your use case allows. A ticket bound to neither a user_id nor an actor_id is anonymous.
Vanity tickets
POST /session/tickets issues four kinds of tickets. Each redirects to a different vanity host route:
ticket_type | URL host + path | Required body | Flow guide |
|---|---|---|---|
agent_access | https://{backend_host}/vanity/agents?ticket=… | agent_ids, actor_id | (this page) |
impersonation | https://{frontend_host}/sign-in?ticket=… | user_id | Console "impersonate user" action |
api_auth_access | https://{backend_host}/vanity/api-auth?ticket=… | api_auth_app_slug | API-auth vanity pages |
webhook_app_access | https://{backend_host}/vanity/webhook?ticket=… | webhook_app_slug | Webhook vanity pages |
Tickets are one-time-redeemable and expire per expires_at. There's no explicit revocation — set a short expires_in (seconds) when you need tight bounds.
Backend vs console issuance
Two endpoints with the same body shape:
POST /session/ticketson the backend host —createBackendSessionTicket. Authenticated withWACHT_API_KEY. Use from server code.POST /session/ticketson the console host —createSessionTicket. Authenticated with an admin OAuth session. Used by the console UI.
Both produce the same vanity URL.