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

# Gate services API

> Create, update, and disable organization-owned Gate services with a secret key, including service IDs, branding, env vars, and registry visibility.

Use `/v1/gate/services` to manage the Gate services owned by your organization.

These endpoints are business-authenticated:

* send `Authorization: Bearer sk_*`
* require `gate:services:read` for reads
* require `gate:services:manage` for create, update, and delete

## Endpoints

* `GET /v1/gate/services` — List the Gate services owned by the authenticated organization
* `GET /v1/gate/services/{serviceId}` — Load one organization-owned Gate service
* `POST /v1/gate/services` — Create a new organization-owned Gate service
* `PATCH /v1/gate/services/{serviceId}` — Partially update an organization-owned Gate service
* `DELETE /v1/gate/services/{serviceId}` — Soft-disable an organization-owned Gate service

## Service IDs

`service_id` is the canonical public slug used everywhere, including `npx signup <service>`.

Rules:

* lowercase only
* `3-32` characters
* may contain `a-z`, `0-9`, `_`, and `-`
* must start and end with a letter or number

Reserved IDs such as `gate`, `registry`, `services`, and `webhook` cannot be claimed by customer organizations.

## Organization limits

Each organization may have at most `5` Gate services total.

* disabled services still count toward the cap
* the built-in `foil` service is system-owned and does not count against any organization

## Visibility

Managed service resources include read-only operational metadata such as:

* `status`
* `created_at`
* `updated_at`

A service appears in `GET /v1/gate/registry` only when it is both `active` and `discoverable`.

Customer-managed Gate services are allowlist-based. Organizations can configure only:

* `id`, `name`, `description`, `website`, `discoverable`
* `webhook_endpoint_id`
* `dashboard_login_url`
* `docs_url`
* `env_vars` as `{ name, key, secret }`
* `sdks` as ordered `{ label, install, url }` entries
* `branding.logo_url`, `branding.primary_color`, `branding.secondary_color`, `branding.ascii_art`
* `consent.terms_url`, `consent.privacy_url`

Everything else is Gate-owned and is rejected on write by default. That includes Gate API URLs, dashboard login env-key metadata, consent copy/scopes, and Gate-managed env-var keys.

Additional notes:

* `webhook_endpoint_id` is required and must reference an active first-class webhook endpoint subscribed to `gate.session.approved`.
* Webhook URLs, subscriptions, signing secrets, test sends, and event history are managed from the Webhooks API and dashboard page.
* Gate-owned login credentials are delivered separately from customer `env_vars` and use the derived key `<SERVICE_ID>_GATE_AGENT_TOKEN`.
* The `branding.verified` badge is managed internally and returned as read-only metadata.
* `branding.primary_color` and `branding.secondary_color` must use hex formats such as `#RGB`, `#RGBA`, `#RRGGBB`, or `#RRGGBBAA`.
* `website` is required on every Gate service. Gate stores it explicitly rather than inferring it from docs, webhook, or dashboard URLs.

See the [OpenAPI spec](/api-reference/introduction) for the full schemas and examples.