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

# Keys and Authentication

> Use an embed key in the browser and a secret key on your servers to read your brand's content from the Seam Manufacturer API.

The Manufacturer API reads public data, so you can call it without a key by naming a manufacturer. A key identifies you. A manufacturer key also scopes requests to your brand, and a manufacturer secret key unlocks your own device models that are hidden from everyone else.

There are two kinds of key:

| | Embed key | Secret key |
| - | - | - |
| Prefix | `eco_live_` | `eco_sk_` |
| Use it in | Web pages and browsers | Your servers only |
| Send it as | `X-Embed-Key` header or `embed_key` query parameter | `Authorization: Bearer eco_sk_…` header |
| Protected by | The origins registered for the key | Keeping it secret |
| Returns | Public data only | Public data, plus your own hidden device models with `include_forbidden=true` |
| Responses | Cacheable by CDNs | Never cached (`no-store`) |

Neither key is a Seam API key. They work only with the Seam Ecosystem API at `https://ecosystem.seam.co`, and a Seam API key does not work there.

## Get Your Keys

Create and revoke keys yourself in [Seam Console](https://console.seam.co): go to **Organization settings** > **Partner profile** > **Keys**. Members of your Console organization can create embed keys and secret keys there, and edit an embed key's name and origins.

* **Manufacturer keys** are available once Seam has confirmed that your organization represents the manufacturer. Until then, the Keys screen shows "Waiting for Seam to confirm".
* If your organization is not linked to a manufacturer or partner yet, email [support@getseam.com](mailto:support@getseam.com) to have it linked.

Apps that integrate with Seam can also get keys, owned by the app instead of a manufacturer. An app key does not scope requests to a manufacturer.

## Embed Keys

An embed key is meant to be public. Put it in your page's HTML, or use it with [Ecosystem Components](/docs/ui-components/overview/ecosystem-components/index) such as [Supported Devices](/docs/ui-components/overview/ecosystem-components/supported-devices).

A browser sends the page's origin with every request, and Seam checks it against the origins registered for your key:

* A request from a registered origin succeeds.
* A request from any other origin fails with `403 origin_not_allowed`.

Because of this, someone who copies your embed key cannot use it on their own site.

When you create an embed key, enter **full origins**, including the scheme and any non-default port:

```
https://www.example.com
https://example.com
https://*.preview.example.com
```

* `example.com` without a scheme matches nothing.
* `https://example.com` and `https://www.example.com` are different origins. List each one you use.
* Use `*` as a wildcard, for example `https://*.preview.example.com` for your preview subdomains. A wildcard subdomain does not match the bare domain, so list `https://example.com` separately.
* `http://localhost` and `http://127.0.0.1` on any port are always allowed, so your key also works on your development server.

To add or remove origins later, select **Edit** on the key in Console's **Keys** screen. The key itself doesn't change, so you don't need to update your pages. The new origins take effect within a minute, and requests from an origin you remove start failing with `403 origin_not_allowed`.

Send the key in the `X-Embed-Key` header:

```javascript theme={"dark"}
const response = await fetch(
  'https://ecosystem.seam.co/v1/device_models/summaries/list?limit=10',
  { headers: { 'X-Embed-Key': 'eco_live_your_embed_key' } },
)
const { device_models } = await response.json()
```

Or, where you cannot set headers, in the `embed_key` query parameter:

```
https://ecosystem.seam.co/v1/manufacturer_content/get?embed_key=eco_live_your_embed_key
```

<Note>
  An embed key is not a server credential. It only ever returns public data, and its rate limit is shared with everyone who sends the key from the same IP address. On your servers, use a secret key.
</Note>

## Secret Keys

A secret key is for server-to-server requests. Send it as a bearer token:

```bash theme={"dark"}
curl --compressed \
  -H "Authorization: Bearer eco_sk_your_secret_key" \
  "https://ecosystem.seam.co/v1/manufacturer_content/get"
```

Treat a secret key like a password:

* Keep it in your server's secret store or environment. Never put it in a web page, a mobile app, or a code repository.
* Console shows a secret key only once, when you create it, and Seam stores only a hash of it. If you lose it, revoke it and create a new one.
* If a secret key is exposed, revoke it in Console right away. A revoked key fails with `401 invalid_secret_key`.

Secret keys work only for reading published data from the Seam Ecosystem API, including the [Manufacturer API](/docs/device-manufacturer-guidance/manufacturer-api/index) endpoints. They do not grant access to anything else.

## What a Manufacturer Key Changes

A manufacturer key, embed or secret, implies your brand:

* [`manufacturer_content/get`](/docs/device-manufacturer-guidance/manufacturer-api/manufacturer-content) returns your content without `manufacturer_slug`. Naming a different manufacturer fails with `403 manufacturer_mismatch`.
* [`device_models/summaries/list`](/docs/device-manufacturer-guidance/manufacturer-api/device-model-summaries) lists your device models by default. Set `manufacturer` to list another manufacturer's public models instead.
* [Supported Devices](/docs/ui-components/overview/ecosystem-components/supported-devices) shows your devices without a `manufacturer` attribute.

### Hidden Device Models

Some device models are marked as forbidden to third parties (`is_forbidden_to_3dparty: true`). Seam hides them from everyone except the model's manufacturer.

To include your own hidden models, send your manufacturer **secret** key with `include_forbidden=true`:

```bash theme={"dark"}
curl --compressed -G \
  -H "Authorization: Bearer eco_sk_your_secret_key" \
  "https://ecosystem.seam.co/v1/manufacturer_content/get" \
  -d include_forbidden=true
```

Embed keys never return hidden models, even with `include_forbidden=true`. Without a manufacturer secret key, the parameter is ignored and you get the public models.

## Next Steps

* Read your brand's content with [Get Manufacturer Content](/docs/device-manufacturer-guidance/manufacturer-api/manufacturer-content).
* Review [errors, rate limits, and caching](/docs/device-manufacturer-guidance/manufacturer-api/index#errors) in the overview.
* Embed your device list on your website with [Supported Devices](/docs/ui-components/overview/ecosystem-components/supported-devices).


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