Issue a Session Token
Give an open session a new widget token, and the widget_url that carries it.
Every session is born with one: the session_token its creation returned, inside its widget_url. Call this while the session is open, when that link has to change hands — it leaked into a log, it was sent to the wrong person, your customer moved to another device — or to give a session whose token you revoked a new one.
The token the session had opens nothing from this moment, and neither does any link built with it: a widget still open on the old link stops at its next step. There is one token per session — issuing is replacing.
Key technical details:
- No request body. The answer carries the new
session_token, itswidget_urland itsexpiration_date— the session’s own, which a new token does not move. - Only while there is something left to do (
409). A closed session, or one past itsdate_limit, gets no new token; its current one can still be revoked. - Concurrency lock (
504). Issuing holds the session; if it cannot within a few seconds, retry.
The widget_url carries no way back of its own: append completion_url (and completion_mode) to it exactly as to the one the creation returned, when the session sets none.
This endpoint needs to be executed with an app secret, so should always be used in server side without exposing the secret to customers.
Authentication
Path parameters
Response
200 OK
The new token and its widget link
The token your customer’s widget acts on this one session with. It reads no results, and it
opens nothing once it is revoked or replaced, or the session’s date_limit has passed. Deleting
the session does not end it: revoke it, before or after the deletion, when the link must stop.
Where to send the end user, carrying this token: open it in an iframe, a new tab or a web view.
When the session sets no way back of its own, you may append one to it: completion_url and
completion_mode.
When the token is deleted, with the session: at least a day after its date_limit, past which
it already opens nothing. Issuing another token does not move it.