List zones

client.zones.list(?, ?): ZoneListResponse { items, page_info, pagination }

GET/zones

Returns a list of zones for the authenticated organization

ParametersExpand Collapse

query: ZoneListParams { after, before, cursor, 3 more }

after?: string

Cursor for forward pagination

minLength1

maxLength255

before?: string

Cursor for backward pagination

minLength1

maxLength255

cursor?: string

expand?: "total_count" | "permissions" | Array<"total_count" | "permissions">

Accepts one of the following:

"total_count" | "permissions"

"total_count"

"permissions"

Array<"total_count" | "permissions">

"total_count"

"permissions"

limit?: number

Maximum number of items to return

minimum1

maximum100

slug?: string

ReturnsExpand Collapse

ZoneListResponse { items, page_info, pagination }

items: Array<Zone { id, created_at, name, 12 more } >

id: string

Unique identifier of the zone

created_at: string

Entity creation timestamp

formatdate-time

name: string

Human-readable name

minLength1

maxLength255

organization_id: string

Organization that owns this zone

protocols: Protocols { oauth2, openid }

Protocol configuration for a zone

oauth2: Oauth2 { authorization_endpoint, authorization_server_metadata, dcr_enabled, 6 more }

OAuth 2.0 protocol configuration for a zone

authorization_endpoint: string

OAuth 2.0 authorization endpoint

formaturi

authorization_server_metadata: string

OAuth 2.0 Authorization Server Metadata endpoint (.well-known/oauth-authorization-server)

formaturi

dcr_enabled: boolean

Whether Dynamic Client Registration is enabled

issuer: string

OAuth 2.0 issuer identifier

formaturi

jwks_uri: string

JSON Web Key Set endpoint

formaturi

pkce_required: boolean

Whether PKCE is required for authorization code flows

redirect_uri: string

OAuth 2.0 redirect URI for this zone

formaturi

registration_endpoint: string

OAuth 2.0 Dynamic Client Registration endpoint

formaturi

token_endpoint: string

OAuth 2.0 token endpoint

formaturi

openid: Openid { provider_configuration, userinfo_endpoint }

OpenID Connect protocol configuration for a zone

provider_configuration: string

OpenID Connect Provider Configuration endpoint (.well-known/openid-configuration)

formaturi

userinfo_endpoint: string

OpenID Connect UserInfo endpoint

formaturi

slug: string

URL-safe identifier, unique within the zone

minLength1

maxLength63

updated_at: string

Entity update timestamp

formatdate-time

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

description?: string | null

Human-readable description

maxLength2048

encryption_key?: EncryptionKeyAwsKmsConfig { arn, type }

AWS KMS configuration for zone encryption. When not specified, the default Keycard Cloud encryption key will be used.

arn: string

AWS KMS Key ARN for encrypting the zone's data

minLength1

type: "aws"

login_flow?: "default" | "identifier_first"

Login flow style for the zone. 'default' uses standard authentication, 'identifier_first' uses identifier-based provider routing.

Accepts one of the following:

"default"

"identifier_first"

permissions?: Record<string, Record<string, boolean>>

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.

requires_invitation?: boolean

Whether the zone requires an invitation for email/password registration, only applies when user_identity_provider_id is not set

user_identity_provider_id?: string

Provider ID configured for user login

page_info: PageInfoPagination { has_next_page, has_previous_page, end_cursor, start_cursor }

Pagination information

has_next_page: boolean

Whether there are more items after the current page

has_previous_page: boolean

Whether there are items before the current page

end_cursor?: string | null

Cursor pointing to the last item in the current page

start_cursor?: string | null

Cursor pointing to the first item in the current page

pagination: Pagination { after_cursor, before_cursor, total_count }

Cursor-based pagination metadata

after_cursor: string | null

An opaque cursor used for paginating through a list of results

minLength1

maxLength255

before_cursor: string | null

An opaque cursor used for paginating through a list of results

minLength1

maxLength255

total_count?: number

Total number of items matching the query. Only included when expand[]=total_count is requested.

List zones

import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const zones = await client.zones.list();

console.log(zones.items);

{
  "items": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "name": "x",
      "organization_id": "organization_id",
      "protocols": {
        "oauth2": {
          "authorization_endpoint": "https://example.com",
          "authorization_server_metadata": "https://example.com",
          "dcr_enabled": true,
          "issuer": "https://example.com",
          "jwks_uri": "https://example.com",
          "pkce_required": true,
          "redirect_uri": "https://example.com",
          "registration_endpoint": "https://example.com",
          "token_endpoint": "https://example.com"
        },
        "openid": {
          "provider_configuration": "https://example.com",
          "userinfo_endpoint": "https://example.com"
        }
      },
      "slug": "slug",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "default_mcp_gateway_application_id": "default_mcp_gateway_application_id",
      "default_resource_id": "default_resource_id",
      "description": "description",
      "encryption_key": {
        "arn": "x",
        "type": "aws"
      },
      "login_flow": "default",
      "permissions": {
        "zones": {
          "read": true,
          "update": true,
          "delete": false,
          "create": false
        },
        "applications": {
          "read": true,
          "list": true,
          "create": false
        }
      },
      "requires_invitation": true,
      "user_identity_provider_id": "user_identity_provider_id"
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": true,
    "end_cursor": "end_cursor",
    "start_cursor": "start_cursor"
  },
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}

Returns Examples

{
  "items": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "name": "x",
      "organization_id": "organization_id",
      "protocols": {
        "oauth2": {
          "authorization_endpoint": "https://example.com",
          "authorization_server_metadata": "https://example.com",
          "dcr_enabled": true,
          "issuer": "https://example.com",
          "jwks_uri": "https://example.com",
          "pkce_required": true,
          "redirect_uri": "https://example.com",
          "registration_endpoint": "https://example.com",
          "token_endpoint": "https://example.com"
        },
        "openid": {
          "provider_configuration": "https://example.com",
          "userinfo_endpoint": "https://example.com"
        }
      },
      "slug": "slug",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "default_mcp_gateway_application_id": "default_mcp_gateway_application_id",
      "default_resource_id": "default_resource_id",
      "description": "description",
      "encryption_key": {
        "arn": "x",
        "type": "aws"
      },
      "login_flow": "default",
      "permissions": {
        "zones": {
          "read": true,
          "update": true,
          "delete": false,
          "create": false
        },
        "applications": {
          "read": true,
          "list": true,
          "create": false
        }
      },
      "requires_invitation": true,
      "user_identity_provider_id": "user_identity_provider_id"
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": true,
    "end_cursor": "end_cursor",
    "start_cursor": "start_cursor"
  },
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}