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

# Partner Overview

> Build widgets for your customers with the Widgetic API and show them in your platform

Partners build widgets for their own customers with the Widgetic API, and show them in their own platform with the embed code. In preview, you can also mount Widgetic's own editors (a file browser, a composition editor, the AI widget creator and the screen where workflows are built) in your own page for one customer at a time, without your API key ever reaching the browser.

## What Partners Can Do

> [card] Build and Embed Widgets
>
> Create compositions with the API and show the published widgets in your platform with the embed code

> [card] Keep Track of End-Users
>
> Keep a record of your customers as managed users

> [card] [Editors in Your Page (preview)](https://widgetic.com/docs/partners/ui-components.md)
>
> Mount Widgetic's File Browser, composition editor, AI widget creator and Workflows in your own page for one customer at a time

> [card] [Credits & Billing](https://widgetic.com/docs/partners/credits-billing.md)
>
> Pay by invoice, with tax, and track the AI credits on your account

> [card] [Your Own Storage](https://widgetic.com/docs/partners/storage.md)
>
> Your customers' files are kept in a bucket you own

> [card] [Dashboard and Analytics](https://widgetic.com/docs/partners/dashboard.md)
>
> Your credits, invoices, customers and presets, and how their widgets are viewed

> [card] [Notifications](https://widgetic.com/docs/partners/notifications.md)
>
> Invoices, payments, low credits and pauses, by email and as signed webhooks

## Partner API Key

Partners use API keys with the `wgt_prt_` prefix. These keys have access to:

* All user-level endpoints
* Partner-specific endpoints (managed users, your contract, your invoices and your credits)

A key belongs to the account that administers your partner record. Only a person who is signed in on widgetic.com can make a key: a request made with an API key is refused, so a leaked key cannot be used to make a second one. A key can still list, rename, switch off and delete keys.

A key does everything its account may do, unless you limit it when you make it. A server that only reads your invoices, for example, can hold a key that cannot create anything. See [Limit what a key can do](https://widgetic.com/docs/authentication.md#limit-what-a-key-can-do).

## Your Account Status

A partner account starts **inactive** and has no trial: you pay from the first day, and Widgetic activates the account once your contract is in force and your storage works. An invoice of your contract that is still unpaid after its due date stops the account by itself until it is paid, and Widgetic can also pause an account by hand. While the account is stopped, paused or not yet active, your customers cannot use your widgets or editors, and what you can change is limited to paying, buying credits, your storage, your notifications and your keys. See [Account Status](https://widgetic.com/docs/partners/account-status.md).

## Architecture Overview

```mermaid theme={null}
flowchart TD
    Partner[Your Platform] --> API[Partner API]
    Partner --> Embed[Embed Code]
    API --> Users[Managed Users]
    API --> Compositions[Widgets and Compositions]
    API --> Credits[Credits/Billing]
    API --> Entitlements[Entitlements]
    API --> Sessions[Editor Sessions]
    Embed --> Published[Published Widget]
    Partner --> UI["UI SDK (preview)"]
    UI --> Editors["File Browser, Composition Editor, Widget Creator, Workflows (preview)"]
    Sessions -.-> Editors
```

The dotted line is the short-lived token your server gives the page, so the editors work with one customer's content and your API key stays on your server.

## Key Concepts

### Managed Users

A managed user is a record of one of your customers in your partner registry. It is not a login, and it does not own anything: everything you create through the API belongs to your administering account. What you can do is file a composition, a widget or an upload under a managed user when you create it, and list your account's items by that managed user later, so each of your customers sees only their own. You create and manage managed users via the API.

```bash theme={null}
curl -sS -X POST "https://api.widgetic.com/v1/managed-users" \
  -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "external_id": "your-platform-user-123", "metadata": { "name": "John Doe", "email": "john@example.com" } }'
```

See [Managed Users](https://widgetic.com/docs/partners/managed-users.md) for the full picture.

### Editor Sessions

An editor session is a short-lived token that your server makes for one managed user. Your page gives it to a Widgetic editor, which then reads and changes that customer's content and nothing else. Your API key never reaches the browser. See [Editor Sessions](https://widgetic.com/docs/partners/editor-sessions.md).

### UI Components

> [!NOTE]
>
> **Preview.** The editors are new. They are built and tested, and you can try them now, but small details can still change while this label is on.

The UI SDK (`@widgetic/ui-sdk`) mounts four pieces in your own page. Each draws inside a shadow root, so your page's styles and its own do not touch each other:

* **File Browser**: browse, upload and pick files, from Widgetic's media library or from your own.
* **Composition Editor**: change the texts, pictures, colours and fonts of a widget, beside a live preview.
* **Widget Creator**: the whole Widgetic canvas, with the AI that builds a widget from a description.
* **Workflows**: chain a customer's compositions into a path, with filters between them that decide which composition a visitor sees next.

See [UI Components](https://widgetic.com/docs/partners/ui-components.md) for the SDK and the File Browser, [Canvas Embedding](https://widgetic.com/docs/partners/canvas-embedding.md) for the composition editor and the widget creator, and [Workflows](https://widgetic.com/docs/partners/workflows.md) for the screen where a customer builds a path.

### Preset Widgets

A preset is a widget of your own that you offer your customers as a starting point, under a short key your code uses. Your server lists them and gives a customer a copy (or a composition) of the one they pick. See [Preset Widgets](https://widgetic.com/docs/partners/managed-users.md#preset-widgets).

A workflow of yours can be a starting point too: your customers copy it, with a copy of every widget it chains, and build on it. See [Starting points](https://widgetic.com/docs/partners/workflows.md#starting-points).

### Credits System

You pay Widgetic by invoice, and Widgetic issues each invoice by itself: one for the credits of every billing period, at your price for a credit. Paying it adds those credits to your account, and when they run out you can buy extra credits with one API call. Credits pay for Widgetic's AI: each generation uses 1 credit (the list price of a credit is \$0.10). Creating compositions, embedding widgets, storage and API calls do not use credits. An invoice of your contract that is unpaid after its due date stops the account until it is paid. See [Credits & Billing](https://widgetic.com/docs/partners/credits-billing.md).

## Getting Started

**1. Make Your Partner API Key**

Contact our sales team to become a partner, and tell them the website where you will integrate Widgetic, such as `acme.com`. Widgetic sets up your partner account and records that website as your platform domain, so it and all of its subdomains can always show your widgets (see [Security](https://widgetic.com/resources/security.md#your-platform-is-always-allowed)). The account stays inactive until it is activated (see below). You then sign in and make your own `wgt_prt_` API key under Workspace settings → API keys. The secret is shown once, so store it when you make it. See [Security](https://widgetic.com/resources/security.md) for rotating and deleting keys.

**2. Set Up Your Storage**

Save a bucket of your own on any S3-compatible service with `PUT /partners/{partnerId}/storage`. It is checked before it is saved, and every editor session and every upload with your key needs it. See [Storage](https://widgetic.com/docs/partners/storage.md).

**3. Agree Your Billing and Get Activated**

Read how [credits and billing](https://widgetic.com/docs/partners/credits-billing.md) work, and agree the credits for each billing period, your price for a credit and the start date with Widgetic. Once your contract is in force and your storage works, Widgetic activates your account (see [Account Status](https://widgetic.com/docs/partners/account-status.md)). There is no trial, so your first invoice is issued on the day your contract starts.

**4. Keep Track of Your Customers**

[Create managed users](https://widgetic.com/docs/partners/managed-users.md) for your platform's customers.

**5. Build and Embed Widgets**

Create [compositions](https://widgetic.com/docs/api/compositions.md) with the API, publish them, and show them in your platform with the embed code.

**6. Put the Editors in Your Page (optional)**

Make an [editor session](https://widgetic.com/docs/partners/editor-sessions.md) for the customer who is on the page, and mount a Widgetic editor with the [UI SDK](https://widgetic.com/docs/partners/ui-components.md), so your customers make and change widgets without leaving your product.

**7. Watch Your Account**

Open your [dashboard](https://widgetic.com/docs/partners/dashboard.md) for your credits, invoices, customers and analytics, and set an address for [notifications](https://widgetic.com/docs/partners/notifications.md) so that your own system hears about invoices, low credits, pauses and stops.

## Partner Endpoints

All partner endpoints require a `wgt_prt_` API key. Key endpoints include:

| Endpoint | Description |
| - | - |
| `GET /managed-users` | List your managed users |
| `POST /managed-users` | Create a managed user |
| `POST /managed-users/{id}/editor-sessions` | Make an editor session for one managed user |
| `DELETE /managed-users/{id}/editor-sessions` | End every editor session of a managed user |
| `GET /partners/{id}/presets` | List the widgets you offer as presets |
| `PUT /partners/{id}/presets/{key}` | Offer one of your widgets as a preset, or replace the preset with that key |
| `POST /managed-users/{id}/presets/{key}/copy` | Give a customer a copy of one of your presets |
| `GET /partners/{id}/workflow-presets` | List the workflows you offer as starting points |
| `PUT /partners/{id}/workflow-presets/{key}` | Offer one of your published workflows as a starting point, or replace the one with that key |
| `POST /workspaces/personal/workflows/from-preset` | Start a workflow for a customer (named in a header) from one of your starting points |
| `GET /partners/mine` | Find the partner you administer, its status and its platform domain |
| `GET /partners/{id}/contract` | Read your contract |
| `PUT /partners/{id}/storage` | Set the bucket your customers' files are kept in |
| `GET /partners/{id}/storage/usage` | See what each of your customers keeps in storage |
| `GET /partners/{id}/analytics/summary` | See how your customers' widgets are viewed and used |
| `GET /partners/{id}/notifications` | List what Widgetic told you |
| `PUT /partners/{id}/notifications/settings` | Choose where your notifications go, and set your webhook |
| `GET /invoices/partner/{id}` | List your invoices |
| `GET /credits/user/{userId}/balance` | Check your AI credit balance |
| `POST /partners/{id}/credits/extra-invoice` | Buy extra credits: an invoice that you pay on its page |

> [!NOTE]
>
> See the [API Reference](https://widgetic.com/api-reference/introduction.md) for complete endpoint documentation. Filter by the `Managed Users`, `Partners`, `Credits` and `Invoices` tags.

## Next Steps

> [card] [Managed Users](https://widgetic.com/docs/partners/managed-users.md)
>
> Keep a record of your customers

> [card] [Editor Sessions](https://widgetic.com/docs/partners/editor-sessions.md)
>
> Let a customer use Widgetic's editors in your page

> [card] [Credits & Billing](https://widgetic.com/docs/partners/credits-billing.md)
>
> How you pay and how credits work

> [card] [Account Status](https://widgetic.com/docs/partners/account-status.md)
>
> Activation, pauses and what each one stops


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.