Getting started

This walks you from zero to a running app with a live GraphQL call on a team.

1. Install the CLI

The stayblox CLI handles everything from scaffolding to forwarding live webhooks to your local server.

npm install -g @stayblox/cli

Requires Node 20 or later.

2. Create your account PAT and log in

App authoring uses an account personal access token (PAT). Open the Account panel, go to Developer access tokens, and generate a token with the develop-apps ability. Copy it. It is shown once.

stayblox login --token <your-account-pat>

This stores the token in ~/.config/stayblox/config.json. The account PAT is your authoring credential. It is not the token your app server uses at runtime; that comes in Step 5.

3. Scaffold your app

stayblox app init my-app
cd my-app

This creates an app.toml with sensible defaults, an icon.png placeholder, and a README.md. Open app.toml and fill in the details:

name = "My App"
type = "remote"
distribution = "private"

scopes = ["read_bookings"]
capabilities = []
webhooks = ["booking.confirmed"]
webhook_url = "https://app.example.com/webhooks/stayblox"

See Configuration (app.toml) for every key.

4. Validate and push

Validate before pushing:

stayblox app validate

Then push the app to create the first version:

stayblox app push

For a private app, the server generates a slug and the CLI writes it back to app.toml. For a public app, set slug in app.toml before the first push. See App lifecycle for the version and release model.

5. Install on a team

Install the app on a team you own. This is the step that issues your per-install runtime token and webhook secret:

stayblox app install --team <team-slug>

Output:

Installed my-app on <team-slug>.
Token: stayblox_app_...
Webhook secret: whsec_...
Saved once. Copy now.

Copy both values and store them in your server's environment. The runtime token is what your app server sends on every GraphQL request. The webhook secret is what you use to verify signed calls from Stayblox. Neither is shown again. Use stayblox app token --team <slug> to rotate the token if needed.

6. Make your first GraphQL call

With the runtime token in your server's environment, verify authentication:

curl -s https://api.stayblox.com/developer/api/2026-01/graphql \
  -H "Authorization: Bearer $STAYBLOX_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"query":"{ apiVersion currentApp { name type } }"}'

A valid response:

{ "data": { "apiVersion": "2026-01", "currentApp": { "name": "My App", "type": "remote" } } }

If currentApp is null, the token is missing or invalid.

Credentials at a glance

Credential	How you get it	Where you use it
Account PAT	Account panel → Developer access tokens	CLI and Management API (authoring)
Runtime token	stayblox app install --team <slug>	Authorization: Bearer on every GraphQL request
Webhook secret	Printed alongside the runtime token at install	Verifying HMAC signatures on Stayblox callbacks

Next

• GraphQL reference: browse every GraphQL type and field.
• Signing & security: set up webhook verification.
• Payment apps: build a payment integration.
• Stayblox CLI: forward live webhooks to your dev server.