---
title: Enterprise Setup
description: How to activate and manage Pinchy Enterprise features with a license key.
---

import { Aside } from "@astrojs/starlight/components";

Pinchy Enterprise unlocks features like [Groups](/concepts/groups/), agent access control, and priority support. Activating it takes one step: enter a valid license key.

## Getting a license key

Contact us to get a license key:

- **Trial key** — 14 days, all enterprise features. [Book a call](https://calendly.com/clemenshelm/pinchy-demo) or email [hey@clemenshelm.com](mailto:hey@clemenshelm.com).
- **Paid key** — Annual license, renewable. Same contact.

No credit card required for trials. No per-agent or per-message fees.

## Activating your key

There are two ways to enter your license key. Use whichever fits your workflow.

### Option 1: Settings UI (recommended)

1. Log in as an admin.
2. Go to **Settings → License**.
3. Paste your license key and click **Save**.

The key is validated immediately. If valid, enterprise features activate instantly — no restart needed.

### Option 2: Environment variable

Set `PINCHY_ENTERPRISE_KEY` in your Docker Compose configuration:

```yaml
services:
  pinchy:
    environment:
      - PINCHY_ENTERPRISE_KEY=eyJ...your-key-here
```

Then restart the container:

```bash
docker compose up -d
```

<Aside type="tip">
  The environment variable takes priority over a key entered in the Settings UI.
  If both are set, the env var wins.
</Aside>

## Verifying your key

After entering a key, go to **Settings → License**. You should see:

- **License type** — Trial or Paid
- **Organization** — The name tied to your key
- **Expiry date** — When the key expires
- **Days remaining**

The enterprise features (Groups tab, agent access control) should now be available.

## Seat cap enforcement

Enterprise license tokens include a `maxUsers` field that limits how many seats your organisation can use. A seat counts as either an **active user** or a **valid pending invitation** — both consume a seat.

### What "at cap" means

When `seatsUsed >= maxUsers`:

- The **Invite User** button in **Settings → Users** is disabled and a banner explains why.
- The **Settings → License** page shows the current seat count next to the cap (`7 / 10 seats used`).
- Attempting to create an invite via the API returns `403 Forbidden` with `{ "error": "Seat limit reached" }`.
- **No existing users are locked out.** Pinchy never deactivates an account to enforce a cap. Only new invitations are blocked.

### Freeing up a seat

To invite someone new when you are at cap, you can:

1. **Revoke a pending invitation** — if an invite was sent but not yet claimed, revoking it frees the seat immediately.
2. **Deactivate an existing user** — deactivated users no longer count toward the seat total.

Both actions take effect immediately — the invite button re-enables without a page reload.

### Trials and unlimited licenses

A `maxUsers` value of **0** means unlimited seats. Trial keys issued by Pinchy carry `maxUsers: 0`, so seat enforcement does not apply during a trial. Paid keys include the seat count negotiated with your order.

<Aside type="note">
  The seat count shown in **Settings → License** includes both active users and
  pending invitations. If the count looks higher than expected, check for
  unclaimed invites in **Settings → Users**.
</Aside>

## What happens when a key expires

Pinchy degrades gracefully. Nothing breaks:

- Agents with **Restricted** visibility fall back to **All users** — everyone can access them.
- Group assignments stay in the database but are not enforced.
- The audit trail continues to work.
- All data, agents, and configuration remain intact.

Renew your key and permissions are restored instantly.

<Aside type="note">
  Admins see a warning banner when the key is close to expiring: 30 days before
  for paid keys, 7 days for trial keys.
</Aside>

## Enterprise features

This is the canonical list of features that require an active Pinchy Enterprise license. Any feature documented elsewhere with an `Enterprise` badge or a "Enterprise feature" callout maps to one of the rows below.

| Feature                  | Where it appears                                                     | Documentation                                              |
| ------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------- |
| Groups                   | Settings → Groups                                                    | [Groups](/concepts/groups/)                                |
| Agent Access Control     | Agent Settings → **Access** tab (visibility modes, group assignment) | [Agent Settings](/concepts/agent-settings/#access-tab)     |
| Group-scoped invites     | Settings → Users → **Invite User** (Groups field when inviting)      | [User Management](/guides/user-management/#inviting-users) |
| Per-user usage breakdown | Usage Dashboard → **Per-User Breakdown** card                        | [Usage Dashboard](/guides/usage-dashboard/)                |
| Usage CSV export         | Usage Dashboard → **Export CSV** button                              | [Usage Dashboard](/guides/usage-dashboard/#export)         |
| Priority Support         | Direct contact with the Pinchy team with priority response times     | —                                                          |

When a license is not active, Enterprise-gated UI shows clear upgrade prompts rather than hiding completely — so you always know what's available.

## Offline validation

License keys are validated locally using cryptographic signatures. No internet connection is required — Pinchy never phones home. This makes enterprise features fully compatible with air-gapped and offline deployments.
