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

# Setup

> Set up the CamoAg Embed SDK

## Fetch Secret

The first step is to obtain your embed secret.

1. Go to your CamoAg Account Settings > Embed
2. Copy your embed secret by clicking the "View" button

## Embed Vanity Domain

CamoAg uses cookies to manage authentication sessions. When the platform is embedded in iframes, browsers like Safari treat these cookies as third-party cookies. Because Safari applies strict privacy rules by default, it blocks these cookies—resulting in users being unable to access CamoAg content within the iframe.

Vanity domains allow Safari to treat authentication cookies as first-party thereby enabling reliable login and session handling inside iframes.

E.g. `camoag-embed.example.com` is embedded within `example.com`

* Embed domains must have 3 or more parts. E.g. `camoag-example.com` is not a valid embed domain.
* The top level domain of the embed domain must match the embedding page to support first-party cookies.
  E.g. `example.camoag-embed.com` may run into third-party cookie issues.

<Steps>
  <Step title="Configure the domain in CamoAg">
    1. In CamoAg, navigate to **Account Settings > Embed**.
    2. In the **Embed Domain** field:
       * Enter your domain (e.g., `camoag.myapp.com`)
    3. Click **Save** to apply the configuration.
  </Step>

  <Step title="Update your DNS configuration">
    1. Reach out to CamoAg support with the vanity domain you configured in step 1.
    2. CamoAg will provide DNS records to add to your domain's DNS configuration.
    3. Notify CamoAg support once the DNS records have been added. CamoAg will verify the configuration and enable the domain for use.
  </Step>
</Steps>

## Generate Signed URL

A unique signed embed URL must be generated for each new embed session. The signed
URL must be used within 5 minutes of generation.

The easiest way to generate a signed embed URL is to use the following API endpoint:

```
POST https://<YOUR_EMBED_DOMAIN>/api/v5/auth/embed/build_signed_url
```

### Request Body

```json theme={null}
{
  "embed_secret": "123451234512345",
  "content_path": "/embedded/map",
  "external_id": "Abc123"
}
```

<Warning>
  **Generate signed embed URLs server-side only**

  The embed secret must never be exposed in client-side code (including frontend
  HTML and JavaScript code). For this reason, all signed URLs must be generated
  server-side using code running in a trusted backend environment.
</Warning>

#### Parameters

##### `embed_secret`

Your embed secret key used to sign the request.

##### `content_path`

The iframe will redirect to this URL after the session is verified.

The embedded map can be customized by adding URL query parameters. See [Configurable Map Defaults](/developers/embed-sdk/setup#configurable-map-defaults) for available options.

Example:

```json theme={null}
{
  "content_path": "/embedded/map"
}
```

#### `external_id`

A required, unique user identifier. This is a string containing up to 100 characters. A new user will be created if one does not already exist with this identifier.

Example:

```json theme={null}
{
  "external_id": "Abc123"
}
```

### Response Body

Using the example Request Body above, this is an example response:

```json theme={null}
{
    "signed_embed_url":"https://camoag-embed.example.com/api/v5/auth/embed/login?content_path=/embedded/map&external_id=Abc123&nonce=ad5b227d5ed3464bab5377ee20912694&signature=RT554uJ2_BXnmGNiqNB2u7ASVuvWeLk_yOkLzNq3ixA%3D&timestamp=1764174111"
}
```

## Implementation

Simply assign your signed embed URL to the iframe's `src` attribute. The session will be authenticated and the map will redirect to the value of `content_path`.

```html theme={null}
<iframe src="<signed-embed-url>" />
```

<Note>
  **Iframe Permissions**

  Iframes block access to some features used within the CamoAg Embedded Map. Add the **`allow`** attribute to enable these features. E.g. **`allow="clipboard-write; geolocation"`**
</Note>

#### `clipboard-write`

The embedded map includes many copy-to-clipboard buttons for convenience (e.g. parcel ids, coordinates, etc). Enabling the clipboard-write permission allows the embedded map to write data to the user’s clipboard from user interaction.

```html theme={null}
<iframe src="<signed-embed-url>" allow="clipboard-write" />
```

#### `geolocation`

Enabling the geolocation permission allows the embedded map to request the user’s location through their browser.

```html theme={null}
<iframe src="<signed-embed-url>" allow="geolocation" />
```

## Configurable Map Defaults

You can customize the embedded map by appending URL search parameters to the `content_path`.
This example will initialize the map the parcels layer enabled:

```json theme={null}
{
  "content_path": "/embedded/map?layer=parcels"
}
```

### Default Location

The default map location can be set in multiple ways.

#### Coordinates

Center the map on a specific latitude/longitude:

```
lat: required
lng: required
```

Example:
`?lat=41.881953&lng=-87.632362`

#### Bounds

Fit the map to the specified bounding box using `southwest` and `northeast` coordinates
(each provided as `"lat,lng"`).

```
southwest: required
northeast: required
```

Example:
`?southwest=41.64,-87.87&northeast=42.03,-87.49`

### Layers

Enable one or more layers by including the `layer` parameter.

Examples:

* `?layer=parcels` — Parcels Layer
* `?layer=counties&layer=states` — Counties + States Layers

#### Available Layer Values

* `parcels` — Plat Map
* `farm_sales` — Farm Sales
* `sections` — U.S. Public Land Survey System (Sections)
* `countysubs` — U.S. Public Land Survey System (Township & Range)
* `counties` — U.S. Counties
* `states` — U.S. States
* `common_land_unit` — Common Land Unit (FSA)
* `contours` — Contours