Account authorization

Get authentication state

Returns the current authentication flow state, including code, QR, password, Passkey, session import, or an authenticated terminal state. Passkey states include passkey_required, passkey_pending, passkey_confirmation, and passkey_confirmation_sent; auth_payload may contain WebAuthn public_key material.

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

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.

Path parameters

account_id

stringrequired

Identifier used in the authentication route.

Request body

This endpoint does not require a JSON request body.

Understand the result

Use the documented response fields and HTTP status. Successful 204 responses have no body; use X-Request-Id for diagnosis. Follow the related operations for the next step.

Response 200 OK

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

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.

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

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.

format: date-time

last_error

string

Most recent authentication error, or an empty string when there is none.

Responses

200

200 OK

Request succeeded. See the example response body.

401

Unauthorized

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

500

Internal Server Error

The service encountered an unexpected error.

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.