Integrations

API keys, the booking widget, and scopes

API keys

An API key lets another website or program talk to your FullClass account. You need one to put the booking widget on your own website, or to connect a tool such as Zapier. If you only use your FullClass booking page, you do not need one. There are two kinds, and they go in different places.

Prefix	Where it lives	How it's secured
`pk_` Public	Browsers, the booking widget, embeds and mobile apps.	It is limited by its scopes (what it may do) and an allowed-origins list (which websites may use it). It is safe in your website's code as long as both are kept tight.
`sk_` Secret	Server code only.	Treat it like a password. Never put it in website code, public code repositories, screenshots, support tickets or website builders. A secret key has full access unless you choose Restricted when you create it and tick only what it may do. Choose that for a key you paste into another service.

Create and revoke keys under Settings → API Keys.
Make new keys when an agency, a supplier or a staff member changes.
Each key shows when it was last used, so you can spot keys nobody needs.

Key safety. A pk_ key is meant to be seen. It sits in your page source, and its scopes are what limit it, so give it only what your website needs. An allowed-origins list is worth setting as well, but know what it does. It stops another website using your key in a browser. It cannot stop someone using the key from their own software, because a program that is not a browser does not send the origin we check. No setting makes an sk_ key safe in a browser.

Booking widget

The widget puts your full booking page, with checkout, inside your own website. You need it only if you want customers to book without leaving your site. Give this part to your web person. They add a container, load the script and start it with a public key:

<div id="booking-widget"></div>
<script src="https://app.fullclass.io/sdk/v1/booking.min.js"></script>
<script>
  FullClassBooking.init({
    apiKey: "pk_your_public_api_key",
    container: "#booking-widget"
  });
</script>

Language: the widget uses the language of your booking page, set in Settings → Booking Widget. There is nothing to add to the code. To keep one embed in another language, add data-fullclass-locale="en" (or locale: "en" in init).
One category per page: if each activity has its own page on your site, open Settings → Categories and click Copy widget code next to the category. Paste it inside the widget's <div> on that page, next to data-fullclass-apikey. That widget then lists only that category and hides the category tabs.
Customisation: built-in languages, your own wording for any text, theme colors, 100+ CSS custom properties, and your own loading, empty and error screens.
Bare mode: pass injectStyles: false to keep the widget's structure without any of its CSS, so your site's own styles apply.
Programmatic control: your page's code can open the gift card purchase, or the booking form for a specific class.
Allowed origins: enter the exact origin, with protocol, subdomain and port. https://www.example.com is a different origin from https://example.com, so list both if you use both. For the key in the ready-made embed code, the quickest place to set this is Settings → Booking Widget, right under the code. If you get it wrong, the widget stops loading for your customers. To undo it, clear the box and save.

Scopes and API capabilities

Scopes are the permissions on a key. They decide what the key can do. Give each key only what it needs. This part is mainly for your web person.

Scope	What it allows
`events:read`	List events and read event details.
`bookings:write`	Create new bookings. Booking in an existing customer's name (`purchaser_type: account`) also needs a secret key.
`bookings:read`	Read the details of existing bookings (from server code).
`bookings:cancel`	Cancel a booking. With a public key, the request must also send the booking's `cancellation_token`.
`customers:write`	Register customer records.
`giftcards:read`	Look up a gift card's balance or remaining classes.
`giftcards:write`	Buy gift cards.

The public API can list events and read event details. It can fetch waivers and add-ons, and create, read and cancel bookings. It can also create and register customers, check promo codes, and look up or buy gift cards. There is no API for spending a gift card. Checkout takes the code inside the booking, and staff use Apply gift card on the booking page.

Idempotency. Always send an idempotency key when your server code creates bookings, so a retry does not book twice.

Gift cards you sold somewhere else

Some studios take the money for a class pass or gift card outside FullClass, for example through a Stripe payment link, a card terminal or a bank transfer. Your server can then have FullClass issue the card without charging the buyer again. Post to /v1/giftcards with an external_purchase block instead of card details:

{
  "type": "class_pass",
  "class_pass_count": 5,
  "purchased_by_email": "[email protected]",
  "external_purchase": {
    "reference": "pi_3RxAbCdEfGhIjKlM",
    "amount_cents": 8000
  }
}

Secret key only. This issues a paid card without taking payment, so a pk_ key is refused. Call it from your server, never from a web page.
The reference stops duplicates. Put the payment's ID from your own system in reference. If the same one arrives twice (a webhook sends again, or a script runs again), the second call is refused and no second card is issued.
You set the price. amount_cents is what you actually collected. It is not checked against your class pass price, so you can sell the same pass at more than one price.
Send the amount with tax included. Send the full amount the buyer paid. For a class pass, FullClass treats it as including the tax you charge on class passes, at the tax rates in your class pass settings.
It counts as a sale. The buyer gets the usual code and receipt emails, and you get the new-sale notification. In your reports the card shows as Paid outside FullClass, not as a giveaway.

← PreviousIntegrations Next →AI assistants