Create zone

POST/zones

Creates a new zone for the authenticated organization. A zone is an isolated environment for IAM resources.

Body ParametersJSONExpand Collapse

name: string

Human-readable name

minLength1

maxLength255

default_mcp_gateway_application: optional boolean

Assign a default MCP Gateway application to the zone

description: optional string

Human-readable description

maxLength2048

encryption_key: optional 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: optional "default" or "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"

protocols: optional object { oauth2 }

Protocol configuration for zone creation

oauth2: optional object { dcr_enabled, pkce_required }

OAuth 2.0 protocol configuration for zone creation

dcr_enabled: optional boolean

Whether Dynamic Client Registration is enabled

pkce_required: optional boolean

Whether PKCE is required for authorization code flows

requires_invitation: optional boolean

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

ReturnsExpand Collapse

Zone = object { id, created_at, name, 12 more }

A zone for organizing resources within an organization

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: object { oauth2, openid }

Protocol configuration for a zone

oauth2: object { 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: object { 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: optional string

Application ID configured as the default MCP Gateway for the zone

default_resource_id: optional string

Resource ID configured as the default resource for the zone

description: optional string

Human-readable description

maxLength2048

encryption_key: optional 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: optional "default" or "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: optional map[map[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: optional 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: optional string

Provider ID configured for user login

Create zone

curl https://api.keycard.ai/zones \
    -H 'Content-Type: application/json' \
    -d '{
          "name": "x"
        }'

{
  "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"
}

Returns Examples

{
  "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"
}