Vuoma API docs

Your own account

Use a personal API key to find classes, read your benefits, book or cancel for yourself, and manage eligible work coverage. A staff role does not turn this key into a studio administration key.

Open your account’s API tab or API access, then manage keys. Choose only the permissions your tool needs, copy the key once, and keep it in secure settings. Revoke it from the same page.

Your studio’s operations

For schedules, people, staffing, messages, inventory, and other management workflows, an authorized administrator can create a scoped organization token in studio Settings.

The token needs the exact operation scope and your current role must allow the action at the requested location. Read the live manifest to learn what this connection can do.

Find classes for your account

This request lists the next 30 days. Add the optional from and to dates for a different window.

curl 'https://www.vuoma.com/api/v1/o/willow/personal/schedule' \
  --header "Authorization: Bearer $VUOMA_PERSONAL_KEY"

Discover permitted studio operations

curl 'https://www.vuoma.com/api/v1/o/willow/agent/manifest' \
  --header "Authorization: Bearer $VUOMA_API_TOKEN" \
  --header 'Accept: application/json'

MCP clients

Connect a client that supports Streamable HTTP and a Bearer header to your personal account endpoint:

The server advertises the tools allowed by that key. Store the key in the client’s secure authentication settings.

Siri and ChatGPT

On iPhone, open Account, then API access and Siri & Shortcuts. Enable Siri there to create its dedicated connection and confirm booking changes when prompted.

To use your studio in ChatGPT on the web or your phone, open your studio account’s API tab and choose Connect ChatGPT. Sign in with your usual studio account and review the requested permissions. Return to ChatGPT and select the studio connection to start a conversation. Available tools follow your current role; staff tools require staff access. Revoke the connection from your account’s API tab at any time.

ChatGPT connections are available for studios with a configured integration.

Check purchased products

In studio Settings, open API access and create a Read-only product integration. Select the exact products and read permissions. This key belongs to the organization and remains usable independently of its creator’s personal role; administrators can revoke it at any time.

Keep the key on your server. Read /api/v1/o/willow/integrations/products for permitted products, then query purchases for a signed-in person. Replace both placeholder IDs in this example:

curl 'https://www.vuoma.com/api/v1/o/willow/integrations/purchases?person_id=PERSON_ID&product_ids=PRODUCT_ID' --header "Authorization: Bearer $VUOMA_ORG_KEY"

Check on sign-in or periodically, following next_cursor until it is empty. Native commerce offers, payment programs, and explicitly mapped imported products are supported. Select each relevant product or archived edition; names alone never grant access.

Your app decides which purchase statuses qualify for access. Account for refunds, disputes, cancellation, and outstanding installments. For imported history, inspect verification, source_status, and source_recorded_at; an old receipt does not establish current enrollment. Unknown balances and disputes remain null.

Monetary fields have an amount_scope: an order total may repeat across its product lines and must not be summed per line.

Sign in with a studio account

In studio Settings, open Connected apps and register your app’s exact HTTPS callback URLs. Copy the client ID and discovery URL into an OpenID Connect client library:

Use the authorization code flow with S256 PKCE, a fresh state, and a fresh nonce. Members sign in with their existing studio account and approve the identity fields your app requests. Use the authorization URL supplied by discovery.

Your server exchanges the returned code and validates the ID token’s signature, issuer, audience, expiry, and nonce. Use person_id with the purchase endpoint; do not link accounts by an unverified email address.

Sign-in grants identity only. Your organization key separately grants product reads. Identity tokens expire after ten minutes; refresh tokens are not issued. Your app manages its own session and access checks. Revoking a connection prevents further sign-ins and token use, but does not end sessions your app has already created.

Websites with @vuoma/web

Svelte 5 account entry, dashboards, profiles, memberships, bookings and credit transfers. Use the existing SvelteKit UI controls and managers for accessible forms, navigation and your theme.

# From a reviewed Vuoma source checkout:
npm run verify --workspace @vuoma/web
npm pack --workspace @vuoma/web --ignore-scripts
# Copy the generated archive to your website as vendor/vuoma-web-reviewed.tgz.
# From your website:
npm install ./vendor/vuoma-web-reviewed.tgz svelte sveltekit-ui

Import the session adapter only in server files. Replace YOUR_STUDIO_ID with your exact eight-character studio ID. It is public configuration; an organization API secret is not needed to sign a member in.

// src/lib/server/vuoma.js — server code only
import { create_member_site_adapter } from '@vuoma/web/server/member-site'

export const memberSite = create_member_site_adapter({
  organization_slug: "YOUR_STUDIO_ID",
  api_origin: "https://www.vuoma.com",
})

// src/hooks.server.js — merge with your existing hook
import { memberSite } from '$lib/server/vuoma'
export async function handle({ event, resolve }) {
  await memberSite.restore(event)
  return resolve(event)
}

// src/routes/api/member/session/[action]/+server.js
import { memberSite } from '$lib/server/vuoma'
export const POST = (event) => memberSite.action(event, event.params.action)

Create the account manager in your owning feature manager, pass a live member identity getter, and refresh your loader after sign-in. The view connects its manager lifecycle.

// Owning feature manager (index.svelte.js)
import { create_member_account_access_manager } from '@vuoma/web/member-account-access-manager'

export function create_account_entry_manager({ identity, on_signed_in }) {
  return create_member_account_access_manager({
    identity, endpoint: '/api/member/session', on_signed_in,
  })
}

// Thin view (index.svelte)
<script>
  import MemberAccountAccess from '@vuoma/web/MemberAccountAccess'
  let { manager } = $props()
</script>
<MemberAccountAccess {manager} />

The same-origin action installs Secure HttpOnly session cookies and validates Origin and the action header. Send only display-safe member fields from loaders; never serialize access or refresh tokens. Signup and email activation require the studio’s configured backend and verified email sender.

Apps and API clients with @vuoma/sdk

A framework-neutral JavaScript and TypeScript client for public studio bootstrap, schedule and catalog, plus the existing member sign-in, profile, commerce, refresh and sign-out routes. Use it with React Native or your website’s backend.

# From a reviewed Vuoma source checkout:
npm run verify --workspace @vuoma/sdk
# Copy packages/sdk/artifacts/vuoma-sdk-0.1.1.tgz to your app as vendor/vuoma-sdk-reviewed.tgz.
# From your app:
npm install ./vendor/vuoma-sdk-reviewed.tgz

For a studio’s native app, an administrator opens Organization Settings, Native App Keys, creates a registration, and copies its publishable vuoma_pk_… key. Replace YOUR_PUBLISHABLE_APP_KEY below with that value. The key can ship in the app and grants no private data or staff permissions.

import { createVuomaClient } from '@vuoma/sdk'

// Replace this placeholder with your registered publishable app key.
const vuoma = createVuomaClient({
  apiOrigin: "https://www.vuoma.com",
  organizationSlug: "willow",
  appKey: 'YOUR_PUBLISHABLE_APP_KEY',
  fetch: globalThis.fetch,
})

const bootstrap = await vuoma.public.getBootstrap()
const catalog = await vuoma.public.getCatalog() // Public studio data only.

Native member requests use the signed-in member’s organization-scoped session as well as the registered app key. The session is bound to that registration; stripping or swapping the key cannot bypass revocation or switch studios. Your host owns refresh and logout: keep access tokens in memory and refresh tokens in Keychain or Keystore through a secure-storage adapter.

import { createVuomaClient } from '@vuoma/sdk'

// Organization Settings, Native App Keys supplies the public appKey.
// sessionStore is your native secure session adapter.
const memberClient = createVuomaClient({
  apiOrigin: "https://www.vuoma.com",
  organizationSlug: "willow",
  appKey: 'YOUR_PUBLISHABLE_APP_KEY',
  fetch: globalThis.fetch,
  tokenAdapter: { getSession: () => sessionStore.current() },
})

const session = await memberClient.auth.signIn({ email, password })
await sessionStore.install(session)
const profile = await memberClient.member.getProfile()

The SDK rejects organization API secrets, platform-account tokens and identity-only OAuth tokens in its member client. Vuoma allows credentials-free CORS on the registered app’s member routes and refresh/sign-out endpoints, using X-Vuoma-App-Key and the member’s explicit Bearer token for private calls. Cookies confer no app authority. For browser account requests, use your same-origin server adapter.