Tebex keys & security

Connecting a Tebex store means trusting Joely with API keys to your business. This page explains exactly what each key does, what Joely reads and writes with it, and how the keys are protected. Every statement here describes enforced behavior in the platform, not intentions.

The three keys

Key	Tebex API	Required	What it unlocks in Joely
Public token	Headless API	Yes	Your public package catalog (names, descriptions, categories) for package pickers and AI package matching.
Private key	Checkout API	Optional	Order detail lookup: tickets open already tied to a verified purchase, and staff see order details on the ticket.
Game server secret key	Plugin API	Optional	A customer's purchase history on the portal and in the ticket view, the details of orders the Checkout API cannot return (such as manual payments), plus coupon, gift card and manual payment creation from a ticket.

Only the public token is required to connect a store. The optional keys can be added later from project settings, and both the private key and the game server secret key can be removed at any time from the store's edit form; the features they power simply stop working until a new key is added. The public token cannot be removed: it is the store's anchor, so the only way to revoke it is to disconnect the store. The Tebex step of onboarding is skippable: you can connect a store later from project settings, or never.

What Joely reads

All reads happen on demand, when a ticket or a page actually needs the data. There is no background sync of your store.

Packages: names, descriptions, and categories from your public catalog.
Order details: transaction ID, products, amounts, discounts, payment method, and the buyer's Cfx.re username for a specific order. Some orders, such as manual payments created from your Tebex panel or from a ticket, cannot be read through the Checkout API. Joely then reads them through the Plugin API (game server secret key), which only returns the order total: these orders list their products without a per-product price. With only the game server secret key, staff can still open a customer's order details; the purchase history needs the private key to show which products an order contains.
Purchase history: a customer's completed payments, used to verify purchases and show order history (requires the game server secret key).

Joely never reads buyer emails or IP addresses: those fields are intentionally excluded from the order details we request and display.

What Joely writes

Write access is limited to three staff-triggered actions, all requiring the game server secret key and explicit permissions (Create Tebex coupons from tickets, Create Tebex gift cards from tickets, Create Tebex manual payments (deliver packages for free) from tickets):

Creating a coupon code from a ticket.
Creating a gift card from a ticket.
Creating a manual payment from a ticket: the selected packages are delivered to a player at a price of 0, after a confirmation step.

Joely never issues refunds, never edits packages or prices, and never touches your checkout.

How keys are stored

Each store gets its own unique data encryption key. Your Tebex credentials are encrypted with it using AES-256-GCM, and that key is itself encrypted by an application master key kept outside the database (envelope encryption).
Keys are encrypted before they reach the database and are never stored in plain text.
Once saved, keys are never returned by the API and never displayed again, not even to you.

Staying in control

You can regenerate any key from your Tebex Developer Dashboard at any time. The old key stops working instantly, which cuts Joely's access on the spot.
Removing a store from project settings deletes its stored credentials.
Store management is permission-controlled (Add Tebex stores, Update Tebex stores, Remove Tebex stores); see Roles & permissions.