# Declare your providers and cookies

Declare each third party that runs on your site, including its category, script hostnames and cookies or storage entries. Consent uses this declaration to block resources, explain the choices in the banner and build your Cookie Declaration page.

## Before you start

- Product access with `write` permission to create or edit providers; deleting a provider requires `admin`.
- Each provider's hostnames and storage entries, including their purpose, duration and storage type.

## The fields

| Field | Required | Use |
|---|---|---|
| `name` | yes | Provider name, unique within your product |
| `category` | yes | `necessary`, `preferences`, `statistics` or `marketing` |
| `hosts` | Depends on category | Up to 50 hostnames; rules below |
| `description` | no | Description shown to visitors |
| `privacyUrl` | no | Provider's privacy policy URL |
| `orderIndex` | no | Display order |
| `cookies` | no | Declared cookies and storage entries |

### Hosts

Use lowercase hostnames with at least one dot, such as `google-analytics.com` or `connect.facebook.net`. Leave out schemes, ports, paths, query strings, fragments and `*`. Single-label hosts are rejected.

A host also matches its subdomains: `google-analytics.com` covers `www.google-analytics.com`. See [Script blocking](/privacy/script-blocking).

Host requirements depend on the category:

- `necessary` requires an empty `hosts` list, since its resources are disclosed but not blocked.
- Other categories require at least one host, so the provider has a resource the blocker can match.

When you update only the category or hosts, the server checks the result against the other field's stored value.

### Cookies

| Field | Required | Use |
|---|---|---|
| `name` | yes | Cookie or storage key, unique within the provider |
| `purpose` | yes | Nonblank explanation of why it is stored |
| `storageDuration` | yes | Nonblank duration |
| `type` | yes | `http_cookie`, `local_storage` or `session_storage` |

Record the duration the provider actually uses. A blank purpose or duration is rejected on creation and cannot be saved later. Duplicate names within one provider are rejected with an error naming them.

## Create one

1. Collect the provider's fields and cookie details above.
2. Add it in Consent in `app.lepsto.com`, or ask your agent to call `consent_providers_create` with product `write` scope.
3. Read the saved provider and check its hosts, category and cookies before testing on your site.

**UI.** The provider picker includes a catalog of known trackers with suggested names, categories, hosts, descriptions, privacy links and cookies. Selecting one creates an editable copy; later catalog changes do not update it. No catalog entry uses `necessary`.

**MCP.** For example, ask:

> "Declare Google Analytics as a statistics provider: hosts google-analytics.com and googletagmanager.com; cookies `_ga` (analytics id, 2 years) and `_ga_*` (session state, 2 years), both type `http_cookie`."

These are example cookie descriptions and durations; check them against your site's configuration before saving. Use `consent_providers_list` to read providers, `consent_providers_update` to edit one and `consent_providers_delete` to remove one. Deletion needs `admin` scope. A provider id from another product is not accessible through these calls.

## Check it worked

1. Read `consent_providers_list` or the app's provider list. Confirm the saved values and cookies, returned in name order.
2. Open your site in a fresh browser profile. Before allowing the category, check that the **Network** panel has no requests to its declared hosts.
3. Open the [Cookie Declaration page](/privacy/declaration-page). The provider and cookies should appear after its cache refreshes, within about five minutes.

## Two details of the update semantics

- Sending `cookies` replaces the entire set. Omit it to preserve existing cookies; send `[]` to remove all of them.
- Send `privacyUrl: null` to clear the privacy link. Omit the field to preserve it.

Mutation responses re-read the saved provider and return cookies sorted by name, just like the list operation. Each successful change emits `consent.config.changed` with the actor, surface and changed fields.

## Adding a provider re-asks the visitor

Creating a provider increments its consentable category's provider-set version. Moving a provider increments the destination category's version. Returning visitors who allowed that category under an earlier version see the banner again with their previous choice filled in. Their stored choice remains in force until they make a new decision.

Renaming, changing descriptions or privacy links, reordering, editing hosts or cookies, and deleting a provider do not increment the version. `necessary` has no version counter. Coordinate additions to avoid asking visitors again after each separate rollout.

## Two providers you do not create

**Lepsto Consent** is built in. It appears first under `necessary`, with the `lepsto_consent` cookie, in the banner, runtime configuration and declaration page. You cannot edit or remove it. A product with no custom providers still has this entry.

**Lepsto Tracking** has a catalog entry that discloses its first-party cookies (`_lt_aid`, `_lt_sid`, `_lt_p`) without host blocking. These cookies are written on your own domain. Keeping the script loaded lets it respond to consent changes; its cookies are cleared on withdrawal. This behavior is controlled by the catalog and is not an option you can give an arbitrary provider.

On pages using the Lepsto banner, also set `data-consent="banner"` on the tracking snippet. See [What tracking does with a consent answer](/privacy/tracking-consent).

## Next steps

- [Script blocking](/privacy/script-blocking): understand what the declared hosts control.
- [Publish a Cookie Declaration page](/privacy/declaration-page): make the declaration available on your site.