---
title: "List zones"
method: GET
path: "/zones"
tags: ["Zones"]
---

# List zones

`GET /zones`

## Request

- Base URL: `https://docs.keycard.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.keycard.ai/zones`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `/service-account-token`

Returns a list of zones for the authenticated organization. Cursor pagination via `after`/`before` and `limit`, plus `expand[]=total_count`, name substring search, and `sort`, are supported on every request. `filter[permission][in]` narrows the list to zones where the caller holds at least one of the given permissions.

## Query parameters

- `slug` string
- `cursor` string
- `after` string
- `before` string
- `limit` integer
- `expand[]` union
  - 'total_count' | 'permissions'
  - string[]
- `filter[organization_id]` string
- `filter[permission][in]` union
  - string
  - string[]

## Response `200`

Default Response

- object
  - `items` IamZone[], required
    - `id` string, required: Unique identifier of the zone
    - `organization_id` string, required: Organization that owns this zone
    - `slug` string, required: URL-safe identifier, unique within the zone
    - `name` string, required: Human-readable name
    - `description` string, nullable: Human-readable description
    - `user_identity_provider_id` string: Provider ID configured for user login
    - `external_sync_enabled` boolean, required: Whether external directory sync (SCIM) is enabled for this zone. Required to create external sync tokens.
    - `protocols` object, required: Protocol configuration for a zone
      - `oauth2` IamZoneOAuth2Protocol, required: OAuth 2.0 protocol configuration for a zone
        - `issuer` string, uri, required: OAuth 2.0 issuer identifier
        - `authorization_server_metadata` string, uri, required: OAuth 2.0 Authorization Server Metadata endpoint (.well-known/oauth-authorization-server)
        - `authorization_endpoint` string, uri, required: OAuth 2.0 authorization endpoint
        - `token_endpoint` string, uri, required: OAuth 2.0 token endpoint
        - `redirect_uri` string, uri, required: OAuth 2.0 redirect URI for this zone
        - `registration_endpoint` string, uri, required: OAuth 2.0 Dynamic Client Registration endpoint
        - `jwks_uri` string, uri, required: JSON Web Key Set endpoint
        - `pkce_required` boolean, required: Whether PKCE is required for authorization code flows
        - `dcr_enabled` boolean, required: Whether Dynamic Client Registration is enabled
        - `cimd` IamZoneCimd, required: Client ID Metadata Document auto-provisioning configuration
          - `enabled` boolean, required: Whether CIMD auto-provisioning is enabled for unregistered URL-based clients
          - `allowed_client_ids` string[], required: Allowlist for CIMD client_id URLs. Each entry is an exact URL, a wildcard origin with a single * replacing one subdomain label (e.g. https://*.example.com matches https://app.example.com but not https://a.b.example.com), or the literal * to allow any client. Only one * is permitted per entry.
      - `openid` IamZoneOpenIDProtocol, required: OpenID Connect protocol configuration for a zone
        - `provider_configuration` string, uri, required: OpenID Connect Provider Configuration endpoint (.well-known/openid-configuration)
        - `userinfo_endpoint` string, uri, required: OpenID Connect UserInfo endpoint
    - `encryption_key` IamEncryptionKeyAwsKmsConfig: AWS KMS configuration for zone encryption. When not specified, the default Keycard Cloud encryption key will be used.
      - `type` 'aws', required
      - `arn` string, required: AWS KMS Key ARN for encrypting the zone's data
    - `default_mcp_gateway_application_id` string: Application ID configured as the default MCP Gateway for the zone
    - `default_resource_id` string: Resource ID configured as the default resource for the zone
    - `permissions` IamPermissions: Permissions granted to the authenticated principal. Only populated when expand[]=permissions query parameter is provided. Keys are resource types, values are objects mapping action names to boolean values.
    - `owner_type` 'platform' | 'customer', required: Who owns this zone. Platform-owned zones cannot be modified via API.
    - `created_at` string, date-time, required: Entity creation timestamp
    - `updated_at` string, date-time, required: Entity update timestamp
  - `page_info` IamPageInfo, required: Pagination information
    - `has_next_page` boolean, required: Whether there are more items after the current page
    - `has_previous_page` boolean, required: Whether there are items before the current page
    - `start_cursor` string, nullable: Cursor pointing to the first item in the current page
    - `end_cursor` string, nullable: Cursor pointing to the last item in the current page
  - `pagination` IamPagination, required: Cursor-based pagination metadata
    - `after_cursor` string, required: An opaque cursor used for paginating through a list of results
    - `before_cursor` string, required: An opaque cursor used for paginating through a list of results
    - `total_count` integer: Total number of items matching the query. Only included when expand[]=total_count is requested.

## Other responses

- `default`: Error response

## Changes

- **2026-10-29** `0dee67e0a73a`: 1 warning, 1 info
  - removed the optional property `items/items/requires_invitation` from the response with the `200` status
  - added the new optional `query` request parameter `filter[permission][in]`
- **2026-10-16** `0cfaff865771`: 3 breaking, 2 warning, 3 info
  - the `page_info` response's property type changed from `object` to no type for status `200`
  - removed the required property `page_info/has_next_page` from the response with the `200` status
  - removed the required property `page_info/has_previous_page` from the response with the `200` status
  - removed the optional property `page_info/end_cursor` from the response with the `200` status
  - …4 more
- **2026-06-09** `7e0e4fa2e16f`: 1 info
  - added the required property `items/items/owner_type` to the response with the `200` status
- **2026-05-18** `2861899ae69e`: 1 warning, 1 info
  - removed the optional property `items/items/login_flow` from the response with the `200` status
  - added the required property `items/items/protocols/oauth2/cimd` to the response with the `200` status
- **2026-05-12** `2fc8ca0cc773`: 1 info
  - added the new optional `query` request parameter `filter[organization_id]`

[Operation history](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/changes/zones/get.md)

---

[API](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api.md) - [All operations](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/revisions/0dee67e0a73a?raw)