AuthenticationPOST

Start code authentication

Starts a verification-code login flow. After this call, submit the provider code through /auth/code. If two-factor auth is required, continue with /auth/password. WhatsApp uses this same endpoint for phone-number pairing — the phone number is read from the account (saved at creation through provider_data.phone) and does not need to be supplied here.

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

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.

Response body

account_id

string

Provider account this response refers to.

status

string

Current authentication flow state, including passkey_required, passkey_pending, passkey_confirmation, passkey_confirmation_sent, authorized, or failed.

auth_fields[]

object[]

Describes what the next step requires — each entry carries a type and whether it is required.

type

string

Input type required by the next authentication step, such as code or password.

required

boolean

Whether the authentication input must be provided.

label

string

Provider-supplied display label for the input, when available.

placeholder

string

Provider-supplied input placeholder, when available.

auth_payload

object

Material needed for the next step, such as qr_code, verify_code, WebAuthn public_key, or a Passkey confirmation prompt.

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.

Request

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/auth/start \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "data": {
    "account_id": "acc_example",
    "status": "awaiting_code",
    "auth_fields": [
      { "type": "code", "required": true }
    ],
    "auth_payload": {
      "verify_code": "ABCD-EFGH"
    },
    "expires_at": "2026-01-01T00:00:00Z"
  }
}