Account authorization

Start QR authentication

Starts a QR login flow for providers using auth_mode=qrcode. Poll /auth or call /auth/qr/check to retrieve the QR content; for some providers the QR is delivered asynchronously over webhook instead of synchronously in the response body.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/auth/qr/start

Supported channels

TelegramWhatsAppLINEZaloTikTok

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Prepare your parameters

account_id: Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account

Request parameters

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Content-Type

stringrequired

Use application/json when sending a JSON request body.

Path parameters

account_id

stringrequired

Identifier used in the authentication route.

Request body

This endpoint accepts an empty JSON object; send {} exactly as shown in the request example.

Understand the result

Read status/auth_status and any auth_payload for the requested authorization action. Follow the channel guide when user input is needed; authorized means authorization is complete. Check runtime_status before sending messages.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "status": "awaiting_qr_scan",
    "auth_payload": {
      "qr_code": "https://example.com/qr"
    },
    "expires_at": "2026-01-01T00:00:00Z"
  }
}

Response body

account_id

string

Provider account this response refers to.

provider

string

Channel identifier. Use the API value unchanged in later calls; see the enum below for the values returned by this endpoint.

action

string

Action requested by this call.

status

string

Current authorization flow status, for example pending_auth, awaiting_qr_scan, awaiting_code, pending, passkey_required, passkey_pending, passkey_confirmation, passkey_confirmation_sent, authorized, or failed.

auth_status

string

Current normalized authentication state, such as awaiting_qr_scan, awaiting_code, passkey_required, authorized or failed. Continue the corresponding channel authorization flow according to this value.

auth_payload

object

Standard payload needed for the current step. QR uses qr_code; code verification uses type=code; Passkey uses type=passkey and public_key. Mutually exclusive step payloads do not appear together.

expires_at

string

RFC3339 timestamp after which the current auth_payload is no longer valid.

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

500

Internal Server Error

The service encountered an unexpected error.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

If the request fails

Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

invalid_request · 10000 · 400: Check required fields, formats and channel conditions, then correct the request.
missing_api_key · 11000 · 401: Check X-Api-Key and whether the workspace is active.
invalid_api_key · 11001 · 401: Check X-Api-Key and whether the workspace is active.
account_already_authorized · 20016 · 409: The account is already authorized. Reuse it, or cancel authorization before starting a fresh flow.