Connect

Device link

For an assistant that cannot complete OAuth. The buyer opens a link, signs in and taps Connect. There is no key to copy.

View as Markdown

Most clients connect with OAuth and never need this page. The device link exists only for an assistant that cannot complete an OAuth sign-in. It follows RFC 8628.

#Steps

Start. The assistant sends:

POST https://mcp.xekta.com/assistant/device
{"client_name": "..."}

Hand over. It gives the buyer verification_uri_complete and the user_code from the answer.
The buyer connects. They open the link, sign in to XEKTA, check the code matches and tap Connect.
Poll. Every interval seconds the assistant sends:

POST https://mcp.xekta.com/assistant/token
{"device_code": "..."}

Use the token. When the answer carries access_token, send it on every MCP request:

Authorization: Bearer <access_token>

#Poll answers

Answer	Meaning	What to do
`authorization_pending`	The buyer has not tapped Connect yet.	Keep polling at `interval`.
`slow_down`	You are polling too fast.	Wait longer between polls.
`access_denied`	The buyer said no.	Stop.
`expired_token`	The link ran out.	Start again with a new link.

#Lost tokens

For 10 minutes after the buyer taps Connect, polling with the same device_code returns a new token that replaces the previous one. After that, a lost token needs a new link. Starting again with the same client_name replaces the old token.

#Approval on these connections

On a device-link connection, cart_approve returns confirm_in_assistant: XEKTA texts a 4-digit code to the buyer's phone, the buyer gives the code to the assistant, and the assistant calls cart_confirm with it. Over $200, or over $300 in 24 hours, the buyer approves on a link, signed in on their own device. See Approval.

Note

Device links are for buyers only.