# Matching your brand

The embedded game takes three settings from your account — a background colour, a font, and a corner radius — so the table reads as part of your site rather than a window into someone else’s.

## The three settings

Chosen in [the portal](/docs/portal.md), per environment. Saving one takes up to **60 seconds** to reach the frame, the same window a [rotated key](/docs/authentication.md#rotating-a-key) waits out — so a reload straight after saving can still show you the old look, and that is not a save that failed.

> **The colour you save is not the exact colour you typed.** Your background sets the table’s hue; we set its lightness, so our near-white text and translucent panels stay legible against it. The portal’s preview shows the result you will actually get before you save it.

The font is one of a fixed set of named faces already on the player’s own device — `ours`, `system-sans`, `system-serif`, `helvetica`, `georgia`, or `mono` — never a file you host or link; there is no way to point the frame at a font of your own. Corner radius is one of `sharp`, `soft`, or `round`.

## What stays ours

The gold highlight that marks a playable card and the accent that marks your opponent stay ours: those colours carry meaning on the board itself, and recolouring them would take information away from a player rather than restyle the table around them. The corner radius follows the same line: it reshapes panels, buttons, chips and modals, and leaves the playing cards alone — a card’s rounded corner is part of what makes it read as a card. The portal’s preview is the game’s own end-of-match modal, so you see the setting on the chrome it actually reshapes.

## Reading and setting it from the API

`GET /partner/theme` answers with the theme for the environment your key names — there is no environment parameter, because every call on this surface takes it from the key. Two keys, two answers.

```
GET /partner/theme
Authorization: Bearer pgs_test_…

{
  "environment": "test",
  "background": "#3b1d6e",
  "font": "system-sans",
  "corners": "sharp",
  "derived": {
    "felt0": "#342d48",
    "felt1": "#221e2f",
    "felt2": "#0d0b13"
  }
}
```

`derived` is the three-step felt we compute from your background — your hue, our lightness — and it is what the frame actually paints. It is `null` when `background` is empty, which is what “use ours” looks like on the wire. Read it rather than deriving your own: a second calculation is a second answer that can disagree with the document we serve.

`logo` is your own mark, or `null`. It is two fields rather than a `data:` URI, because we build the URI ourselves when we write it into your embed:

```
"logo": {
  "mime": "image/png",
  "base64": "iVBORw0KGgoAAAAA…"
}
```

`mime` is `image/png` or `image/webp` — never SVG, which is a document and can carry scripts. `base64` is the file's bytes on their own, with no `data:` prefix, and at most 32 KB decoded — export it around `256×256`, which is what the limit is sized for: the mark is drawn at 84 px, so 256 covers a three-times display and a 1024×1024 export is four times more pixels than anything will ever show. All four refusals, and why the size is a bound rather than a preference, are in [Errors and limits](/docs/errors.md).

> **Send it only when you mean to change it.** Omit `logo` and your stored mark is left alone — which is what a call written before marks existed does, so it cannot delete one. Send `null` to remove it. Send nothing at all and your players see your background alone; they never see ours.

`PUT /partner/theme` takes the same settings and answers with the stored result. It accepts a **test key only**: a live key reading is fine, a live key writing is refused with [live_theme_not_writable](/docs/errors.md).

> **A write is a deploy.** The theme lives on your account, so setting it repaints every embed in that environment — your staging site, your QA, your CI — not a copy belonging to the call. That is why test is the automatable one: it is where you iterate against your own page. Changing live is done in the portal, beside a preview, by a person.

The refusals both calls answer are in [Errors and limits](/docs/errors.md). Where the settings land on the page — the frame itself, the origins that decide who may embed it, and the messages it exchanges with yours — is [Embedding a game](/docs/embedding.md).