> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tipstack.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# Whitelist Your Domain for Tip Stack Embeds

> Tip Stack enforces origin whitelisting to prevent unauthorized sites from embedding your widget. Add your domain in the creator dashboard before going live.

Every time your Tip Stack widget loads, the server checks the embedding page's origin against a list of domains you have explicitly approved. If the origin is not on your list, the widget refuses to initialize. This mechanism protects you from clickjacking and prevents other sites from embedding your tip jar without your permission.

<Warning>
  Always whitelist your production domain before deploying the widget. Unwhitelisted embeds will silently fail for your visitors.
</Warning>

## Why origin whitelisting exists

Without origin validation, any site on the internet could copy your embed snippet and render your Tip Stack widget on their page. A malicious actor could use this to collect tips that should be going to you, trick your audience, or execute clickjacking attacks by overlaying invisible iframes.

Tip Stack enforces whitelisting at the server level on every `/sdk/init` request. The check happens before any session token is issued, so an unauthorized embed cannot proceed past the initialization step.

## How it works

When your widget script runs, it sends a `POST /api/sdk/init` request that includes the embedding page's `originUrl`. The Tip Stack server compares it against the list of domains you have approved in your creator dashboard:

* **Match found** — a `sessionToken` is issued and the widget loads successfully.
* **No match** — the server returns a `403 Unauthorized Origin` response and the widget does not render.

`localhost` and `127.0.0.1` are automatically treated as trusted during local development. You do not need to add them to your whitelist.

## What a blocked embed looks like

When a request is rejected, the server responds with:

```json theme={null}
{
  "error": "Unauthorized Origin",
  "message": "This domain is not authorized to embed this TipLnk widget. Please add it in your creator dashboard."
}
```

The widget container on the page remains empty. Visitors see nothing — there is no error displayed to them.

## Add your domain

<Steps>
  <Step title="Open your creator dashboard">
    Go to [tipstack.fun/dashboard](https://tipstack.fun/dashboard) and sign in with your creator account.
  </Step>

  <Step title="Navigate to Embedded Domains">
    Select **Settings** from the left sidebar, then click the **Embedded Domains** tab.
  </Step>

  <Step title="Enter your origin">
    Type the full origin of your site into the input field and click **Add Domain**. The origin must include the protocol and must not have a trailing slash.

    ```
    https://myblog.com
    ```

    ```
    https://myapp.vercel.app
    ```

    ```
    https://mycreator.webflow.io
    ```
  </Step>

  <Step title="Save and deploy">
    Your new origin is active immediately — no rebuild or re-deploy is needed. Reload your embedded page to verify the widget appears.
  </Step>
</Steps>

## Origin format rules

Getting the origin format exactly right is important. The server performs a strict string comparison — there is no wildcard or subdomain matching.

<CardGroup cols={2}>
  <Card title="Correct format" icon="circle-check">
    Include the protocol and omit the trailing slash.

    * `https://myblog.com`
    * `https://www.myblog.com`
    * `https://myapp.vercel.app`
    * `http://staging.internal.company.com`
  </Card>

  <Card title="Will not match" icon="circle-xmark">
    These formats will fail validation even if the domain is correct.

    * `myblog.com` — missing protocol
    * `https://myblog.com/` — trailing slash
    * `https://*.myblog.com` — wildcards not supported
    * `myblog.com/blog` — paths are not origins
  </Card>
</CardGroup>

<Tip>
  `www.myblog.com` and `myblog.com` are treated as **different origins**. If your site serves traffic on both, add both entries separately.
</Tip>

## Multiple domains

You can add as many whitelisted origins as you need. Common scenarios where multiple entries are useful:

| Scenario                       | Origins to add                                        |
| ------------------------------ | ----------------------------------------------------- |
| Production + staging           | `https://myblog.com` and `https://staging.myblog.com` |
| Custom domain + Vercel preview | `https://myblog.com` and `https://myblog.vercel.app`  |
| www and apex                   | `https://www.myblog.com` and `https://myblog.com`     |
| Multiple content sites         | One entry per domain                                  |

## Remove a domain

To revoke a domain, return to **Settings → Embedded Domains**, click the **×** next to the origin you want to remove, and confirm. Widgets embedded on that domain will stop working immediately on their next page load.

<Note>
  Removing a domain does not affect any active sessions that were already initialized before the removal. Those sessions remain valid until they expire.
</Note>