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://vuoma.com/api/v1/o/willow/personal/schedule' \
  --header "Authorization: Bearer $VUOMA_PERSONAL_KEY"

Discover permitted studio operations

curl 'https://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://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/svelte

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.

npm install --save-exact @vuoma/svelte@0.2.1 sveltekit-ui@1.1.91

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/svelte/server/member-site'

export const memberSite = create_member_site_adapter({
  organization_slug: "YOUR_STUDIO_ID",
  api_origin: "https://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/svelte/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/svelte/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 reads, signup and email verification, password setup, sign-in, profile, commerce, class and appointment bookings, cancellation and reconciliation. Use it with React Native or your website’s backend. Keep the same request ID when reconciling an uncertain booking; the client does not silently retry a purchase or booking.

npm install --save-exact @vuoma/sdk@0.2.3

Each studio app includes its studio slug as public configuration. No app registration or public app key is needed. Public schedule and catalog requests can be made without signing in.

import { createVuomaClient } from '@vuoma/sdk'

const vuoma = createVuomaClient({
  apiOrigin: "https://vuoma.com",
  organizationSlug: "willow",
  fetch: globalThis.fetch,
})

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

Native member requests send the signed-in member’s bearer token. The server verifies the live session, studio membership and current permissions; changing the studio slug cannot grant access to another studio. 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'

// sessionStore is your native secure session adapter.
const memberClient = createVuomaClient({
  apiOrigin: "https://vuoma.com",
  organizationSlug: "willow",
  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. Private native calls use the member’s explicit Bearer token. Browser cookie requests keep their same-origin protections. For browser account requests, use your same-origin server adapter.