A valid request URL is required to generate request examples{
"token": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"portal_url": "<string>"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Enter a contact's account
Requires customers:impersonate — its own permission, held by owner and deliberately not by admin. It answers the support call nobody can answer from the outside: what your customer’s screen actually renders.
What comes back is a real contact session token (uk_ct_…), not a fifth kind of credential. The same routes accept it, the same JWT is minted from it and the same revocation document ends it — which is the point, since the whole purpose is to see what the customer sees. Four things make it a support session rather than theirs:
- fifteen minutes, not renewable. The expiry is on the session itself, so the JWTs minted from it are capped by it. Longer means starting another one, which is a second line in the audit log rather than an open door.
impersonated: truein every JWT minted from it. Your backend gets the claim on every refresh, synchronously, which is where a decision like “support may read this and may not delete it” belongs — only you know which of your acts are the destructive ones.- the routes that change credentials are refused with
403 impersonated_session: revoking the contact’s own sessions, and the team’s own API keys. Reading the device list is allowed. - the contact can see it.
GET /v1/contact/meanswers animpersonationobject for as long as the session lives, and the session appears on their own device list flagged as support.
It does not count toward the active-contact meter, no email is sent, and nothing is written to the contact’s own sign-in history — support’s address must not teach the new-address warning that your office is somewhere this person signs in from.
Refused for an anonymous visitor (contact_anonymous: there is no account to enter) and while somebody is already inside (impersonation_active: two open doors make “end it” ambiguous). The action is recorded in the audit log as contact.impersonation_started, with who did it and from where.
A valid request URL is required to generate request examples{
"token": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"portal_url": "<string>"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Path Parameters
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Response
The session.
A uk_ct_… contact session token. Treat it as the credential it is: it should reach a browser through something that cannot be read back — a fragment exchanged immediately for an httpOnly cookie — never a query string, which lands in history and in the next page's Referer.
Fifteen minutes out. There is no refresh: when this passes, the session is gone.
Where the token is meant to be spent, with the environment's publishable key already on it so the page can tell whose product it is drawing. The token is deliberately not in this URL.