Build apps

Apps are remote integrations that run on your server and connect to Stayblox over the Developer GraphQL API. Stayblox never hosts or executes third-party code. An app is your configuration in app.toml plus the credentials your server uses to authenticate.

Building a storefront theme instead? That is a different surface. Build themes

One app, two distributions

Every app belongs to your account and declares a distribution:

• distribution: private: installable only on teams in your account. No review process, no store listing. Use this for internal automations and custom integrations.
• distribution: public: submitted for review and listed in the Stayblox App Store after approval. Use this for integrations you want to distribute to other hosts.

The app.toml config file is the same for both. Private apps skip review entirely; public apps go through a per-dimension review pipeline.

Two distinct credentials

Keep these separate. They serve different purposes.

Credential	Who holds it	What it is for
Account PAT	You, the developer	Authenticates the CLI and the Management API. Used only for authoring operations. Minted in the Account panel.
Per-install runtime token	Your app server	Authenticates GraphQL API calls your app makes at runtime, scoped to a single team install. Issued by stayblox app install --team <slug>.

What an app can do

General-purpose remote apps (type: remote) are the default. They can subscribe to webhook topics, read the host's data, write back through write mutations, store app-owned metafields on bookings, properties, and contacts, embed a UI page inside the host panel, and let hosts connect through an OAuth flow from your own site.

Two protocol specializations extend the general model:

• Payment apps (type: payment): implement the Stayblox payment-session protocol so hosts can offer your provider at checkout.
• Channel apps (type: channel): implement the ARI push and reservation-ingestion protocol for OTA connections.

Injection apps (type: injection) render sanitized HTML snippets into storefront slots such as analytics pixels and chat widgets. No runtime token is needed; just an app.toml with [[injections]].

All remote types (remote, payment, channel) receive a per-install runtime token and webhook secret when installed on a team.

App types at a glance

remote   ─── GraphQL reads + write mutations + metafields
              + optional: app page (iframe) + OAuth install + webhooks + injections
              + optional: settings schema (per-install config the host enters)

payment  ─── remote + payment-session protocol
              (POST to your endpoint → resolve/reject/pending over GraphQL)

channel  ─── remote + ARI push + reservation-ingestion protocol

injection ── HTML snippet into storefront slots (no runtime token)

CLI-first authoring

Configuration lives in app.toml. You edit it locally and push via the CLI:

stayblox app init               # scaffold app.toml
stayblox app validate           # dry-run validation
stayblox app push               # create or update the app version
stayblox app install --team <slug>   # install on a team; prints the runtime token once

For public apps, the store listing (description, gallery, pricing) and the app icon are managed in the Account-panel Dashboard, not in app.toml. See App lifecycle.

The payment-session flow

 Buyer picks your app at checkout
         │
 Stayblox ──POST {payment_session} (HMAC signed)──▶  your app
         │                                            opens a hosted payment page
 Stayblox ◀──────── { redirect_url } ────────────────┘
         │
   redirect buyer ──▶ your hosted page ──▶ buyer pays
                                             │
 your app ◀──── provider callback / webhook ─┘
         │
 your app ──GraphQL paymentSessionResolve (runtime token)──▶  Stayblox
         │
 Stayblox marks the booking paid; buyer returns to return_url

The session moves through a fixed set of states on the Stayblox side; your mutations drive the transitions. See Payment apps for the full lifecycle and copy-paste examples.

Where to go next

Get started

• Getting started: CLI setup, first push, first GraphQL call.
• Configuration (app.toml): every config key with examples.
• Scopes: what each scope grants and how consent works.
• App lifecycle: distribution, versions, release, and review.

Capabilities

• GraphQL reference: the full schema, generated from the SDL.
• Webhooks: subscribe to topics, verify and process events.
• Metafields: app-owned data on bookings, properties, contacts.
• Injections: render HTML snippets into storefront slots.
• Embedded pages: iframe UI inside the host panel, JWT sessions.
• OAuth install: "Connect your Stayblox account" flow from your site.

Protocols

• Payment apps: session payload, mutations, and examples.
• Channel apps: ARI push and reservation ingestion.
• Inbox channel-provider apps: manifest declaration, inbound message forwarding, outbound delivery commands.

Reference

• Management API: the /dev REST API for authoring.
• Stayblox CLI: full command reference.
• Signing & security: verify our requests, sign yours.
• Versioning: dated API versions, how to pin one.
• Reference app: a complete working Stripe example.