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

# Authentication

> API keys, OAuth Bearer tokens, and optional platform attribution.

## API key (brand-owned)

Brands generate a key on Account Portal → Settings → Integrations. The plaintext key is shown **once**. Branduo stores a hash only.

Send the key on every request:

```http theme={null}
X-Api-Key: bduo_test_…
```

| Environment | Prefix       |
| ----------- | ------------ |
| TEST / DEV  | `bduo_test_` |
| PROD        | `bduo_live_` |

Do **not** put the key in the query string. Keys with the wrong prefix for the host are rejected.

## Optional platform attribution

Tech platforms should also send:

```http theme={null}
X-Platform-Id: e38849db-d0bf-494b-abe9-6bf5f833a34e
```

`X-Platform-Id` is the catalog `Platform.Id` as a Guid string (`type: string`, `format: uuid`). It is **not** a Lookup TypeId and **not** an integer. The former TEST int `4` for Redo is void.

Public example (Redo): `e38849db-d0bf-494b-abe9-6bf5f833a34e`.

| Platform  | `X-Platform-Id` (Guid)                 |
| --------- | -------------------------------------- |
| Klaviyo   | `64c80918-18cd-40d9-a505-37624d1fa7a0` |
| PostPilot | `92e76985-46b7-46cd-9383-b3eca513f10f` |
| Shopify   | `e2c81d5f-9c66-45cb-8321-9bcea954cbca` |
| Redo      | `e38849db-d0bf-494b-abe9-6bf5f833a34e` |

On the first valid call with a known Active Platform Guid, Branduo upserts a `PlatformCompany` link for that brand.

| `X-Platform-Id` value                                     | Result                                                   |
| --------------------------------------------------------- | -------------------------------------------------------- |
| Omitted                                                   | Allowed (MCP-shaped callers). Authenticate and continue. |
| Present but not a uuid (empty, `4`, `redo`, any non-Guid) | **400**                                                  |
| Present, valid Guid, unknown or inactive catalog row      | **400**                                                  |
| Present and Active                                        | Authenticate and upsert `PlatformCompany`                |

Omitting `X-Platform-Id` is allowed (MCP-shaped callers). Header names stay `X-Api-Key`, `Authorization: Bearer`, and `X-Platform-Id`.

## OAuth (optional)

OpenAPI also supports OAuth: short-lived access token (\~1 hour) plus long-lived refresh (\~5 years). Send:

```http theme={null}
Authorization: Bearer <access_token>
```

Endpoints on the OpenAPI host:

* `GET /v1/oauth/authorize`
* `POST /v1/oauth/token`

See Swagger on the OpenAPI host for request/response shapes.