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

# Integrator identity tokens

> Opaque accountToken and productToken fields for enterprise embed widgets and multi-brand orgs.

Enterprise integrators (MCNs, marketplaces, creative automation platforms) run **one YPH org** and map many brands and creators using opaque tokens from **their** database. YPH does not create child orgs per advertiser or creator.

## Fields

| Field          | Resource       | Meaning                                                       |
| -------------- | -------------- | ------------------------------------------------------------- |
| `accountToken` | Digital sample | **Brand** id in your system                                   |
| `productToken` | Digital sample | Optional **catalog product** id (SKU/listing key)             |
| `accountToken` | Actor          | **Creator** id, or **brand** id when the brand owns the actor |
| `accountToken` | Insta swap     | Who initiated the swap — copied from the actor by default     |

`productToken` is **not** the same as `productUrl` (public TikTok Shop / listing URL used in Collab). Use `productToken` for your internal product primary key.

All tokens are optional strings, max **128** characters, scoped to your org. Pass `null` on PATCH to clear.

## Widget filtering rule

Embed UIs should **require** an `accountToken` from your session (brand dashboard or creator app). List endpoints accept `?accountToken=`:

* `GET /digital-samples?accountToken=brand_nike`
* `GET /digital-samples?accountToken=brand_nike&productToken=sku_123`
* `GET /actors?accountToken=creator_42`
* `GET /digital-samples/{id}/insta-swaps?accountToken=creator_42`

**Without a token, widgets should show no rows** — your integrator decides which token to inject per surface.

Server-to-server calls with your API key may omit filters and see the full org.

## Brand self-service vs creator application

Compare the swap token with the parent sample's brand token:

| Sample `accountToken` | Swap `accountToken` | Mode                                                            |
| --------------------- | ------------------- | --------------------------------------------------------------- |
| `brand_nike`          | `creator_42`        | **Creator application** — different parties                     |
| `brand_nike`          | `brand_nike`        | **Brand self-service** — brand creates its own actors and swaps |

The API exposes this on insta swap responses as read-only `isBrandSelfService` (`true` when tokens match).

Typical setup:

1. **Brand** creates sample with `accountToken: "brand_nike"` and optional `productToken`.
2. **Creator** creates actor with `accountToken: "creator_42"`, then `POST …/insta-swaps` with that actor (swap stores `creator_42`).
3. **Brand** approval widgets list swaps where `sampleAccountToken` is the brand token and `accountToken` differs (creator applications).

Brand production widgets list resources where `accountToken` equals the brand token on samples, actors, and swaps.

## Examples

### Create a brand-scoped sample

```bash theme={null}
curl -s https://api.yourproducthere.ai/v1/digital-samples \
  -H "Authorization: Bearer $YPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nike Air Max — winning format",
    "accountToken": "brand_nike",
    "productToken": "sku_air_max_90",
    "seedVideoUrl": "https://cdn.example.com/seeds/nike.mp4"
  }'
```

### Create a creator actor

```bash theme={null}
curl -s https://api.yourproducthere.ai/v1/actors \
  -H "Authorization: Bearer $YPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Michel",
    "accountToken": "creator_42",
    "faceAssetUrl": "https://cdn.example.com/creators/face.jpg",
    "voiceClipUrl": "https://cdn.example.com/creators/voice.mp3"
  }'
```

### Queue a creator swap (tokens differ → not self-service)

```bash theme={null}
curl -s https://api.yourproducthere.ai/v1/digital-samples/$SAMPLE_ID/insta-swaps \
  -H "Authorization: Bearer $YPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actorId": "'"$ACTOR_ID"'",
    "accountToken": "creator_42"
  }'
```

Response includes `sampleAccountToken`, `productToken`, and `isBrandSelfService: false`.

## Security note

`accountToken` values are **identifiers**, not secrets. Never embed your `yph_sk_*` API key in client-side widgets. Phase-2 embed tokens will scope widget calls to a single token and resource set.

## Related

* [Enterprise installation](/guides/enterprise-installation)
* [End-to-end workflow](/guides/workflow)
* [OpenAPI schemas](/api-reference/digital-samples/list-digital-samples)