# Connect self-hosted WordPress with an application password API Reference

Connects one self-hosted WordPress site using a WordPress username and application password.

- `siteUrl` must use HTTPS and may include the path where WordPress is installed.
- Create an application password in the WordPress user's profile; do not send the user's login password.

Zernio discovers the REST API, verifies the credentials and required post/media/taxonomy capabilities, then stores the password encrypted.

Reconnecting the same site and profile updates the connection in place.


## POST /v1/connect/wordpress/token

**Connect self-hosted WordPress with an application password**

Connects one self-hosted WordPress site using a WordPress username and application password.

- `siteUrl` must use HTTPS and may include the path where WordPress is installed.
- Create an application password in the WordPress user's profile; do not send the user's login password.

Zernio discovers the REST API, verifies the credentials and required post/media/taxonomy capabilities, then stores the password encrypted.

Reconnecting the same site and profile updates the connection in place.


### Request Body

- **profileId** (required) `string`: Your Zernio profile ID (get from /v1/profiles).
- **siteUrl** (required) `string`: HTTPS base URL of the WordPress installation, including a subdirectory path when applicable.
- **username** (required) `string`: WordPress login name. A colon is not allowed.
- **applicationPassword** (required) `string`: Application password created for the WordPress user. Spaces in WordPress display formatting are accepted.

### Responses

#### 200: WordPress site connected as a platform account

**Response Body:**

- **account** (required) `object`: 
  - **_id** (required) `string`: No description
  - **platform** (required) `string`: No description - one of: wordpress
  - **username** (required) `string`: Hostname of the connected WordPress site.
  - **displayName** (required) `string`: WordPress site title.
  - **profileId** (required) `string`: No description

#### 400: Malformed body, non-HTTPS `siteUrl`, invalid username, unavailable REST API, or a site that cannot support the required WordPress operations.

#### 401: Invalid API key or WordPress application password.

#### 402: Payment method or enterprise contract required: the authenticated account hit a billing gate before the connection could proceed. Switch on `reason` to render the right prompt:

- `free_tier_exceeded`: the team has connected more accounts than the free tier allows. Add a payment method to continue (billed per additional connected account).
- `twitter_passthrough`: connecting an X account requires a card on file from day one, because X API calls incur real per-call pass-through costs. Applies to the 1st X account, not only the 3rd+.
- `enterprise_required`: the team's enterprise contract sets a connected-account cap and it has been reached. Self-service teams have NO cap (the $1/account rate continues at any scale). The user already has a card on file; this gate is about contract terms.
- `card_verification_required`: the card on file was flagged at add time (prepaid, or issued in a different country than the billing address). A one-time verification charge of `details.verification_amount_cents` (USD) is pending; it is credited to the team's usage balance, not a fee.

**What to do:** redirect the end-user to `dashboard_url`.

- `free_tier_exceeded`, `twitter_passthrough`, `card_verification_required`: it opens the Zernio billing page (the add-payment-method drawer, or the verification step). The request succeeds once the card is on file (or verified, or paid).
- `enterprise_required`: it opens the enterprise contact form (not the billing tab), to adjust the contract's limit.


**Response Body:**

- **error** (required) `string`: Human-readable error message suitable for end-user display. (example: "X (Twitter) requires a payment method due to API pass-through costs. Add a payment method to connect an X account.")
- **code** (required) `string`: Machine-readable error code. Stable across versions. - one of: PAYMENT_REQUIRED
- **reason** (required) `string`: Discriminator for which gate fired. - one of: free_tier_exceeded, twitter_passthrough, enterprise_required, card_verification_required
- **documentation_url** `string` (uri): Link to the relevant documentation page. (example: "https://docs.zernio.com/billing/payment-method-required")
- **dashboard_url** `string` (uri): Deep-link to send the end-user to. For
`free_tier_exceeded` and `twitter_passthrough` this opens
the add-payment-method drawer on the Zernio billing page.
For `enterprise_required` this is the Zernio enterprise
contact page.
 (example: "https://zernio.com/dashboard/billing?add_payment_method=1")
- **details** `object`: Structured context for SDK clients that want to render their own UX. Keys vary by `reason`.
  - **free_tier_account_limit** `integer`: How many accounts the free tier allows. Only set when reason=free_tier_exceeded. (example: 2)
  - **current_account_count** `integer`: How many accounts the team currently has connected. Set when reason=free_tier_exceeded or reason=enterprise_required. (example: 5)
  - **has_payment_method** `boolean`: Whether the team currently has a card on file in Stripe. Set when reason=free_tier_exceeded or reason=twitter_passthrough.
  - **verification_amount_cents** `integer`: One-time card verification charge in USD cents, credited to usage. Only set when reason=card_verification_required. (example: 1000)
  - **effective_account_limit** `integer`: The negotiated connected-account cap from the
team's enterprise contract. Self-service teams
have no cap and never receive this reason. Only
set when reason=enterprise_required.
 (example: 2000)

#### 403: No access to the Zernio profile, or the WordPress user lacks required capabilities.

#### 404: Zernio profile not found or WordPress REST endpoint not found.

#### 502: The WordPress site returned an unclassified upstream error.

#### 503: The WordPress site could not be reached.

---