Skip to main content
Docs
Browse documentation

Guide

Hosted Connect

Let customers authorize supported provider accounts without exposing provider credentials.

On this page
  1. Prerequisites
  2. Create a session
  3. Expected result
  4. Errors
  5. Next step

Prerequisites

Use a server API key with accounts:write. Choose a stable external reference for recovery, a provider supported by the current registry, and a post-authorization redirect owned by your application.

Provider authorization differs: WhatsApp and Telegram support hosted challenge flows, while LinkedIn uses OAuth only when the project has the required partner entitlement. Availability is never inferred from this guide.

Create a session

bash
curl https://api.moiraconnect.com/v1/hosted-connect-sessions \
  -X POST \
  -H "Authorization: Bearer $MOIRA_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data '{"provider":"whatsapp","external_reference":"customer-42","auth_mode":"qr"}'

Redirect the customer to the returned short-lived URL. Do not proxy QR payloads or authentication challenges through browser analytics.

Expected result

The session reaches completed, returns to the allowlisted redirect, and projects an account health state. Reusing the external reference recovers the account instead of silently duplicating it.

Errors

  • 410 hosted_connect_session_expired requires a new session.
  • 503 telegram_capacity_exhausted is temporary and safe to retry later.
  • 403 capability_not_granted means the provider programme or project entitlement is missing.

Next step

Wait for account health to become ready, then list chats before enabling write scopes.