AuthenticationPOST

Create provider authorization session

Creates a short-lived hosted authorization session for a WhatsApp account using auth_mode=qrcode. Open authorize_url in the user’s browser and treat the complete URL as a sensitive credential that must not be logged or shared.

https://api.unifyport.ai/v1/accounts/{account_id}/auth-sessions

Headers

X-Api-Key

stringrequired

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

Path parameters

account_id

stringrequired

Identifier used in the authentication route.

Request body

This endpoint does not require a JSON request body.

Response body

account_id

string

Provider account this response refers to.

provider

string

Canonical provider name in the response. whatsapp-protocol supports only session authentication, and currently supports text, image and contact details; reply, mentions, contact listing and write actions, conversations and groups are not supported. Availability depends on the adapters registered in the deployment.

enum: whatsapp

auth_mode

string

Authentication mode for this authorization session; currently qrcode.

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_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.

authorize_url

string

Short-lived hosted authorization URL containing an opaque credential. Never log or share the complete URL.

format: uri

expires_at

string

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

format: date-time

switchable

boolean

Whether the hosted authorization session allows the user to switch authentication modes.

available_auth_modes[]

string[]

Authentication modes available within the hosted authorization session.

Responses

201

201 Created

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.

500

Internal Server Error

The service encountered an unexpected error.

503

Service Unavailable

A required backend service is temporarily unavailable.

Request

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/auth-sessions \
  -H "X-Api-Key: <YOUR_API_KEY>"

Response

{
  "data": {
    "account_id": "acc_example",
    "provider": "whatsapp",
    "auth_mode": "qrcode",
    "status": "passkey_required",
    "auth_payload": {
      "type": "passkey",
      "public_key": {
        "challenge": "<BASE64URL_CHALLENGE>"
      }
    },
    "authorize_url": "https://auth.example.com/authorize/whatsapp/<SESSION_TOKEN>",
    "expires_at": "2026-08-12T08:10:00Z",
    "switchable": false,
    "available_auth_modes": ["qrcode"]
  }
}