API Reference

Account authorization

Import authentication session

Completes authentication by importing an existing session URL or cookie/session payload. Use placeholder values in client examples and never expose session material in logs.

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

Before you call

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

WhatsApp Protocol is a separate channel identified by provider=whatsapp-protocol. It currently supports only session import (auth_mode=session), using existing session credentials to authorize an account. WhatsApp Protocol authorization

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

session_url
string

URL or reference to an existing provider session artifact.

format: uri

whatsapp-protocol
object

WhatsApp Protocol session import credentials, accepted only by /v1/accounts/{account_id}/auth/session in this nested object, not provider_data. When supplied, phone, static_pub_key, static_pri_key, identity_pub_key and identity_pri_key are required. Responses never echo protocol keys or other sensitive credentials. phone checks identity consistency; protocol public and private keys are used only for upstream startup. edge_routing is injected by the platform and must not be submitted.

phone
string

Phone input may contain spaces, hyphens, parentheses or a plus sign; the server normalizes it to a positive numeric string.

minLength: 1

platform
integer

Platform value for WhatsApp Protocol session import (int32).

format: int32

app_version
string

Application version for WhatsApp Protocol session import.

server_address
string

Provider server address for WhatsApp Protocol session import.

fallback_server_addresses[]
string[]

Fallback server addresses for WhatsApp Protocol session import.

country
string

Country code for WhatsApp Protocol session import.

device
integer

Device value for WhatsApp Protocol session import (uint32).

format: uint32

static_pub_key
string

Protocol public key; write-only.

minLength: 1

static_pri_key
string

Protocol private key; write-only.

minLength: 1

identity_pub_key
string

Identity public key; write-only.

minLength: 1

identity_pri_key
string

Identity private key; write-only.

minLength: 1

hash
string

Deprecated compatibility field; its value is ignored and not stored. Omit it.

peer_kem_public
string

Peer KEM public key; write-only.

auth_hex_data
string

Current authentication data in hexadecimal; write-only.

authhexdata
string

Deprecated legacy authentication data field in hexadecimal; write-only.

pq_handshake_mode
string

PQ handshake mode for WhatsApp Protocol session import.

use_xxkem_handshake
boolean

Whether to use the XXKEM handshake for WhatsApp Protocol session import.

Understand the result

Read the authorization result, then check runtime_status. Session import and an active connection are different milestones.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "status": "authorized"
  }
}

Response body

account_id
string

Provider account this response refers to.

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.

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.
invalid_api_key · 11001 · 401
Check X-Api-Key and whether the workspace is active.
provider_invalid_request · 30001 · 400
Check required fields, formats and channel conditions, then correct the request.