# Wikiup API onboarding for assistants

Use this guide to help a human create a Wikiup account, obtain a server-side API key, select a property, and verify an integration. The [live API reference](https://api.wikiup.app/) documents the full resource contracts. Do not invent endpoints or substitute another product's authentication flow.

## Confirm the intended setup

1. Ask whether the owner wants production (`https://api.wikiup.app`) or preview (`https://api-preview.wikiup.app`). Use that environment consistently for registration, credentials, and property IDs.
2. Ask whether they already have an account. For an existing account, use [Wikiup Console](https://console.wikiup.app/) to sign in or reset the password, then open [API keys](https://console.wikiup.app/api-keys) or use its authenticated session with `POST /api/api-keys` to issue a key. Programmatic registration never adopts an existing identity.
3. For a new account, obtain the email address they own and their given/family names. Request a verification code and wait for the owner to provide it. Never ask for the inbox password, retrieve another person's verification code, or guess a code.
4. Establish where the integration will store credentials. Use a server-side secret manager or protected runtime environment. Never put an API key in frontend code, widget URLs, committed files, screenshots, chat replies, or logs. Disable shell tracing and tool output that would expose secrets.
5. Ask for the actual property details before creating a property. List accessible properties first. Do not create the sample property below without the owner's request.

The examples use `curl`, `jq`, and a POSIX-compatible shell. Replace placeholders with the owner's values. Examples are a sequence; retain the private working directory and variables between steps.

## 1. Request an email verification code

Set the environment and a private temporary directory. Do not place temporary credential files in the repository.

```sh
umask 077
WIKIUP_API_BASE=https://api.wikiup.app
WIKIUP_SETUP_DIR=$(mktemp -d)
```

Send the email address owned by the person registering:

```sh
curl --fail-with-body --silent --show-error \
  -X POST "$WIKIUP_API_BASE/api/accounts/registration" \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com"}' \
  --output "$WIKIUP_SETUP_DIR/challenge.json"
```

Expected status: **202**. Response:

```json
{
  "registrationId": "b5f2a9f1-93c8-4a78-a96b-8dff15e92c14",
  "expiresAt": "2026-10-22T12:30:00.000Z"
}
```

The emailed code contains 10 letters/digits and expires after 30 minutes. Each request has its own registration ID; pair the matching ID and code. Wait for the human to provide the code. Do not continue without it.

Requests have a 60-second per-email cooldown, limits of 5 per email per hour and 20 per client IP per hour. Respect `Retry-After` on a **429** response. Do not loop requests to bypass these limits.

## 2. Confirm the account and privately capture the first key

Prepare a protected JSON request file at `$WIKIUP_SETUP_DIR/confirmation.json` using the challenge ID, the human-supplied code, and their names. Its shape is:

```json
{
  "registrationId": "<registrationId from step 1>",
  "code": "<code supplied by the owner>",
  "givenName": "Alex",
  "familyName": "Morgan"
}
```

Names must be 1–100 characters after trimming. An optional `password` must contain 9–256 characters and at least one number. If it is omitted, the account owner can later use the console password-reset flow to choose a password; an assistant should not request or display their password.

```sh
curl --fail-with-body --silent --show-error \
  -X POST "$WIKIUP_API_BASE/api/accounts/registration/confirm" \
  -H 'Content-Type: application/json' \
  --data-binary "@$WIKIUP_SETUP_DIR/confirmation.json" \
  --output "$WIKIUP_SETUP_DIR/account.json"
```

Expected status: **201**. The response shape below uses a redacted placeholder, not a usable key:

```json
{
  "userId": "user_123",
  "email": "owner@example.com",
  "apiKey": {
    "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "name": "Account setup",
    "prefix": "wk_a1b2c3d4",
    "access": "read_write",
    "propertyIds": null,
    "createdAt": "2026-10-22T12:00:00.000Z",
    "expiresAt": "2027-01-20T12:00:00.000Z",
    "revokedAt": null,
    "key": "<one-time-api-key>"
  }
}
```

Store `apiKey.key` directly in the chosen secret manager. The full key is returned only on issuance. `GET /api/api-keys` returns metadata and cannot recover it. The first key is named **Account setup**, permits read/write across the account's current memberships, and expires after 90 days. No property is created automatically.

For the remaining setup requests, write a private header file without printing the key:

```sh
jq -er '"Authorization: Bearer " + .apiKey.key' \
  "$WIKIUP_SETUP_DIR/account.json" > "$WIKIUP_SETUP_DIR/auth.headers"
```

A key has the format `wk_<32 lowercase hex ID>.<64 lowercase hex secret>`. Treat the whole value as opaque. It is not a guest session or interactive console session.

## 3. List accessible properties

```sh
curl --fail-with-body --silent --show-error \
  "$WIKIUP_API_BASE/api/properties" \
  --header "@$WIKIUP_SETUP_DIR/auth.headers" \
  --output "$WIKIUP_SETUP_DIR/properties.json"
```

Expected status: **200**, with a bare array of memberships. A new account returns `[]`. A membership includes `propertyId`, the `property` object, `isOwner`, `permissions`, and `role`. Select an existing property that matches the owner's request; use its `propertyId`, not a room ID or user ID.

If no property exists and the owner has requested one, continue to step 4. Otherwise skip to step 5.

## 4. Create a property only when needed

The endpoint takes a nested `property` object. Obtain the actual name, contact phone/email, address, and IANA time zone from the owner. The address should include `line1`, `city`, `state`, and `postalCode`. Do not infer a time zone from the assistant's machine. Property and address IDs are generated by the server; supplied IDs and nested members/access groups are ignored.

```sh
curl --fail-with-body --silent --show-error \
  -X POST "$WIKIUP_API_BASE/api/properties" \
  --header "@$WIKIUP_SETUP_DIR/auth.headers" \
  -H 'Content-Type: application/json' \
  -d '{"property":{"name":"Cedar Ridge Inn","phone":"+17605550100","email":"stay@example.com","timeZone":"America/Los_Angeles","address":{"line1":"100 Main Street","city":"Julian","state":"CA","postalCode":"92036","country":"US"}}}' \
  --output "$WIKIUP_SETUP_DIR/property.json"
```

Expected status: **201**. The response is the new owner membership; save its `propertyId`. API key callers need `read_write` and `propertyIds: null` to create a property. A key restricted to existing property IDs cannot create another property.

## 5. Make the first property-scoped request

Set `WIKIUP_PROPERTY_ID` to the selected or newly created membership's ID. Most property-resource endpoints require both the Bearer credential and `x-property-id`.

```sh
WIKIUP_PROPERTY_ID=prop_123
curl --fail-with-body --silent --show-error \
  "$WIKIUP_API_BASE/api/rooms" \
  --header "@$WIKIUP_SETUP_DIR/auth.headers" \
  -H "x-property-id: $WIKIUP_PROPERTY_ID" \
  --output "$WIKIUP_SETUP_DIR/rooms.json"
```

Expected status: **200**, with a bare room array. `[]` is normal before rooms are configured. Do not fabricate rooms, rates, taxes, policies, or payment configuration merely to make the response nonempty.

## 6. Issue a key suited to the integration

Keep the setup credential separate from an integration's daily credential. Choose `read_only` and an explicit property allowlist unless the requested integration needs writes. The account owner creates this key in [Console → API keys](https://console.wikiup.app/api-keys), or uses their authenticated account session with the management API below. An API key cannot list or issue another key.

The following management request requires `WIKIUP_SESSION_TOKEN` from an interactive sign-in completed within the past five minutes. Refreshing an access token alone does not renew the sign-in time. An older or missing sign-in time returns **401** with `code: "REAUTHENTICATION_REQUIRED"`. Reauthenticate through the account’s sign-in method, then retry with the renewed session. Console’s API keys page presents this reauthentication dialog automatically. The setup API key cannot authorize issuance; if no recent session is available, complete this step in Console.

```sh
jq -n --arg propertyId "$WIKIUP_PROPERTY_ID" \
  '{name:"Reporting integration",access:"read_only",propertyIds:[$propertyId],expiresInDays:90}' \
  > "$WIKIUP_SETUP_DIR/key-options.json"
curl --fail-with-body --silent --show-error \
  -X POST "$WIKIUP_API_BASE/api/api-keys" \
  -H "Authorization: Bearer $WIKIUP_SESSION_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary "@$WIKIUP_SETUP_DIR/key-options.json" \
  --output "$WIKIUP_SETUP_DIR/integration-key.json"
```

Expected status: **201**. Unlike registration confirmation, this response is the issued key object directly; the secret is at `.key`, not `.apiKey.key`. Store it securely and test the intended request using that key before switching the integration.

Key options:

- `name`: required, 1–80 trimmed characters.
- `access`: `read_only` (default) or `read_write`.
- `propertyIds`: `null` by default, meaning the owner's current memberships; or 1–100 allowed property IDs. An empty array is invalid. Naming a property never grants membership.
- `expiresInDays`: integer from 1 to 365, default 90. Issue replacements through the console or an authenticated session.

The five-minute sign-in requirement applies only to creating a key. Listing keys and revoking them with a session require a valid account session without that additional freshness check.

An account may have at most 25 active keys. Only an interactive account session can list or issue keys. No API key can manage another key, but any valid API key can revoke itself with `DELETE /api/api-keys/{id}`.

Keys inherit the owner's current property permissions. `read_write` is an access ceiling, not an ownership grant. A `read_only` key also cannot call the reservation `guest-portal-access`, `payment-link`, `confirmation-email`, or `guest-portal-reply-email` GET endpoints: these create access credentials or trigger delivery.

API keys cannot perform account/profile/password actions, read or change connected mailbox messages, connect/disconnect Google email, delete properties, leave memberships, access team or invitation management, or accept invitations. Use an interactive session for those actions. Public widget flows and guest portal sessions use their own documented authentication; do not substitute a staff API key.

## 7. Rotate, clean up, and report

For rotation, use Console or an authenticated account session to create a replacement, store it, and verify it before revoking the previous key. A revoked or expired key cannot authenticate. Record IDs and expiration times without recording the full secret in logs.

```sh
WIKIUP_OLD_KEY_ID='<32-character-key-id>'
curl --fail-with-body --silent --show-error \
  -X DELETE "$WIKIUP_API_BASE/api/api-keys/$WIKIUP_OLD_KEY_ID" \
  -H "Authorization: Bearer $WIKIUP_SESSION_TOKEN"
```

Successful revocation returns **204**, with no JSON response. Use an interactive session to revoke another key. An API key may authenticate only a request to revoke its own ID. Verify the owner can sign in to Console and the replacement integration key works before retiring the setup key.

After credentials are safely stored, remove the protected temporary files, including the verification request and one-time key responses. Clear temporary credential variables. Report the chosen environment, account email, property name/ID, verified operation, key label/access/property scope/expiration, and secret storage location. Do not include the full key, password, code, or registration proof in the report.

## Handle failures without unsafe retries

- **400 registration input/proof errors:** validate the field descriptions and the code's matching registration ID. Do not guess codes. Expired challenges require a new code.
- **409 existing/used registration:** use console sign-in or password reset. Programmatic registration does not issue a key for an existing account.
- **429:** respect `Retry-After`. Five incorrect code attempts exhaust a challenge.
- **503 `REGISTRATION_RECOVERY_REQUIRED`:** setup may have created the account before failing. The registration cannot be replayed to retrieve the key; recover through console sign-in/password reset, then issue a new key.
- **401 `REAUTHENTICATION_REQUIRED` on key creation:** reauthenticate through the owner’s sign-in method or use Console’s API keys page. Do not repeatedly refresh the same session token as a substitute for reauthentication.
- **401 on protected requests:** check the credential's environment, expiration, and revocation. Do not log the credential while diagnosing.
- **403:** check current membership permissions, API key access and property allowlist, and whether the operation requires a session.
- **422 on key creation:** inspect `details` for invalid fields. Unknown body fields are rejected.

Registration error responses use `{ "error": { "code": "...", "message": "..." } }`. API key management errors use `{ "error": "..." }`, with `code: "REAUTHENTICATION_REQUIRED"` when fresh sign-in is needed and `details` for invalid key options. Do not assume one error envelope applies to every Wikiup endpoint.

## Channel management

See [Channel management](https://api.wikiup.app/#channel-management) for the white-label sandbox setup and synchronization contract.

- `GET /api/properties/{id}/channel-management` reads the workspace, pricing terms, dynamic channel catalog, mappings, import coverage and booking issues.
- `POST /api/properties/{id}/channel-management` accepts owner-only actions: `enable`, `connect`, `complete`, `cancel_authorization`, `listings`, `map`, `activate`, `pause`, `remove`, `sync`, `review`, `approve`, `preview_import`, `import`, `publish`, `request_channel`.
- `POST /api/channel-management/authorization` completes an authenticated, owner-bound, expiring channel authorization session.
- `POST /api/channel-management/webhook` is the internal authenticated booking signal receiver. Customers do not supply its secret.

Enablement records versioned pricing acceptance: USD 10/month per independent rental or USD 15/month per hotel property for the first 5 physical rooms, plus USD 1/month per additional room. Vacation-rental portfolios need a quote. Sandbox acceptance creates no charge; production mutations are blocked.

The [complete channel API workflow](https://api.wikiup.app/channel-management-api.md) documents every request and response, including owner API-key access, both pricing plans before enablement, custom callback redirects, direct preview sample-account consent, Vrbo sample credential/code verification, multi-listing room/rate mapping, optional content imports and property-wide review/approval. Use `sync` then `review`; display blockers and require explicit owner approval before `approve`. Do not auto-approve. Never infer that real OTA OAuth can be bypassed because preview permits simulated consent.

Activation starts with inventory closed and requests existing reservations. Imported whole-home listings create one Draft room, not one room per bedroom. Photo imports resume in batches. Reservation history and personal details are limited by source coverage. Review source calendars, missing history, prices and previous integrations before the explicit `publish` action opens sandbox inventory.

Incoming revisions are durably saved before acknowledgment. Mapping failures and reservation conflicts remain unacknowledged and visible. No imported booking creates a payment or guest email. Webhooks and a 15-minute backup polling workflow share the inbox; the workflow must be deployed and its existing preview configuration synchronized before unattended tests. Provider acceptance is not OTA delivery confirmation.

### Preview reservation simulation

Owner-only `GET /api/properties/{id}/channel-management/sandbox-reservations`
returns test reservation delivery and local reservation IDs. Use
`POST /api/properties/{id}/channel-management/sandbox-reservations` on the preview
API to create, modify or cancel synthetic bookings using the normal import
pipeline, or send `action: verify` to reconcile delivery. Requires an enabled
sandbox property with no real connected channels. Simulated preview channels are allowed.
Create/modify/cancel return 202 submitted, not imported. Poll until delivery is
applied. Production rejects this endpoint. See the channel-management API reference
for fields and idempotent UUID requestId handling.

In preview, Add channel → Airbnb authorizes a simulated account and exposes sample
listings for normal import, mapping and activation. Catalog and connection entries
carry simulated:true. No actual Airbnb authorization is performed. Production uses
the real adapter and OAuth flow when production activation becomes available.


## Isolated staging data for PMS integrations

Read [Staging test data](https://api.wikiup.app/staging-test-data.md) for the owner-authorized API setup, Booking CRS prepare/create/modify/cancel/verify commands, delivery states, errors and safe retry rules. Preview can reach real OTA accounts; use a separate property with zero connected channels. Main channel sync is not the ingestion-only verification endpoint.
