openapi: 3.1.0
info:
contact:
email: support@konghq.com
name: Kong Inc
url: https://konghq.com
description: 'OpenAPI 3.0 spec for Kong Gateway''s Admin API.
You can learn more about Kong Gateway at [developer.konghq.com](https://developer.konghq.com).
Give Kong a star at the [Kong/kong](https://github.com/kong/kong) repository.'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
title: Kong Enterprise Admin ACLs Portals API
version: 3.14.0
servers:
- description: Default Admin API URL
url: '{protocol}://{hostname}:{port}{path}'
variables:
hostname:
default: localhost
description: Hostname for Kong's Admin API
path:
default: /
description: Base path for Kong's Admin API
port:
default: '8001'
description: Port for Kong's Admin API
protocol:
default: http
description: Protocol for requests to Kong's Admin API
enum:
- http
- https
security:
- adminToken: []
tags:
- name: Portals
description: APIs related to configuration of Konnect Developer Portals.
paths:
/v3/portals:
get:
x-speakeasy-entity-operation:
terraform-resource: null
terraform-datasource:
- Portal#read
operationId: list-portals
summary: List Portals
description: Lists developer portals defined in this region for this organization. Each developer portal is available at a unique address and has isolated configuration, customization, developers, and applications.
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/SortPortals'
- name: filter
in: query
description: Filter portals returned in the response.
required: false
schema:
$ref: '#/components/schemas/PortalFilterParameters'
style: deepObject
responses:
'200':
$ref: '#/components/responses/ListPortalsResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Portals
post:
x-speakeasy-entity-operation:
terraform-resource: Portal#create
terraform-datasource: null
operationId: create-portal
summary: Create Portal
description: Creates a new developer portal scoped in this region for this organization.
requestBody:
$ref: '#/components/requestBodies/CreatePortal'
responses:
'201':
$ref: '#/components/responses/PortalResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Portals
/v3/portals/{portalId}:
parameters:
- name: portalId
in: path
description: ID of the portal.
required: true
schema:
type: string
format: uuid
x-speakeasy-match: id
get:
x-speakeasy-entity-operation:
terraform-resource: Portal#read
terraform-datasource: null
operationId: get-portal
summary: Get a Portal
description: Returns the configuration for a single developer portal, including the current visibility, access, and domain settings.
responses:
'200':
$ref: '#/components/responses/PortalResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Portals
patch:
x-speakeasy-entity-operation:
terraform-resource: Portal#update
terraform-datasource: null
operationId: update-portal
summary: Update Portal
description: Updates the configuration for a single portal including the visibility, access, and custom domain settings.
requestBody:
$ref: '#/components/requestBodies/UpdatePortal'
responses:
'200':
$ref: '#/components/responses/PortalResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
tags:
- Portals
delete:
x-speakeasy-entity-operation:
terraform-resource: Portal#delete
terraform-datasource: null
operationId: delete-portal
summary: Delete Portal
description: Deletes a single portal, along with all related entities.
parameters:
- name: force
in: query
description: If true, the portal will be deleted, automatically deleting all API publications. If the force param is not set, the deletion will only succeed if there are no APIs currently published.
schema:
type: string
default: 'false'
enum:
- 'true'
- 'false'
responses:
'204':
description: No Content
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Portals
components:
schemas:
InvalidParameterMinimumLength:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
description: invalid parameters rules
type: string
enum:
- min_length
- min_digits
- min_lowercase
- min_uppercase
- min_symbols
- min_items
- min
nullable: false
readOnly: true
x-speakeasy-unknown-values: allow
minimum:
type: integer
example: 8
source:
type: string
example: body
reason:
type: string
example: must have at least 8 characters
readOnly: true
additionalProperties: false
required:
- field
- reason
- rule
- minimum
UpdatedAt:
description: An ISO-8601 timestamp representation of entity update date.
type: string
format: date-time
example: '2022-11-04T20:10:06.927Z'
readOnly: true
x-speakeasy-param-suppress-computed-diff: true
ConflictError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 409
title:
example: Conflict
type:
example: https://httpstatuses.com/409
instance:
example: kong:trace:1234567890
detail:
example: Conflict
InvalidParameterChoiceItem:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
description: invalid parameters rules
type: string
enum:
- enum
nullable: false
readOnly: true
reason:
type: string
example: is a required field
readOnly: true
choices:
type: array
items: {}
minItems: 1
nullable: false
readOnly: true
uniqueItems: true
source:
type: string
example: body
additionalProperties: false
required:
- field
- reason
- rule
- choices
InvalidParameterMaximumLength:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
description: invalid parameters rules
type: string
enum:
- max_length
- max_items
- max
nullable: false
readOnly: true
x-speakeasy-unknown-values: allow
maximum:
type: integer
example: 8
source:
type: string
example: body
reason:
type: string
example: must not have more than 8 characters
readOnly: true
additionalProperties: false
required:
- field
- reason
- rule
- maximum
UuidFieldFilter:
description: 'Filter using **one** of the following operators: `eq`, `oeq`, `neq`'
type: object
properties:
eq:
description: The field exactly matches the provided value.
type: string
oeq:
description: The field matches any of the provided values.
type: string
neq:
description: The field does not match the provided value.
type: string
additionalProperties: false
UUID:
description: Contains a unique identifier used for this resource.
type: string
format: uuid
example: 5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
readOnly: true
PortalFilterParameters:
type: object
properties:
id:
$ref: '#/components/schemas/UuidFieldFilter'
name:
$ref: '#/components/schemas/StringFieldFilter'
description:
$ref: '#/components/schemas/StringFieldFilter'
authentication_enabled:
$ref: '#/components/schemas/BooleanFieldFilter'
rbac_enabled:
$ref: '#/components/schemas/BooleanFieldFilter'
default_api_visibility:
$ref: '#/components/schemas/StringFieldFilter'
default_page_visibility:
$ref: '#/components/schemas/StringFieldFilter'
default_application_auth_strategy_id:
$ref: '#/components/schemas/UuidFieldFilter'
auto_approve_developers:
$ref: '#/components/schemas/BooleanFieldFilter'
auto_approve_applications:
$ref: '#/components/schemas/BooleanFieldFilter'
default_domain:
$ref: '#/components/schemas/StringFieldFilter'
canonical_domain:
$ref: '#/components/schemas/StringFieldFilter'
title: PortalFilterParameters
Labels:
description: "Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. \n\nKeys must be of length 1-63 characters, and cannot start with \"kong\", \"konnect\", \"mesh\", \"kic\", or \"_\".\n"
type: object
example:
env: test
additionalProperties:
type: string
pattern: ^[a-z0-9A-Z]{1}([a-z0-9A-Z-._]*[a-z0-9A-Z]+)?$
minLength: 1
maxLength: 63
maxProperties: 50
title: Labels
ForbiddenError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 403
title:
example: Forbidden
type:
example: https://httpstatuses.com/403
instance:
example: kong:trace:1234567890
detail:
example: Forbidden
UnauthorizedError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 401
title:
example: Unauthorized
type:
example: https://httpstatuses.com/401
instance:
example: kong:trace:1234567890
detail:
example: Invalid credentials
LabelsUpdate:
description: "Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. \n\nLabels are intended to store **INTERNAL** metadata.\n\nKeys must be of length 1-63 characters, and cannot start with \"kong\", \"konnect\", \"mesh\", \"kic\", or \"_\".\n"
type: object
example:
env: test
additionalProperties:
type: string
pattern: ^[a-z0-9A-Z]{1}([a-z0-9A-Z-._]*[a-z0-9A-Z]+)?$
minLength: 1
maxLength: 63
nullable: true
maxProperties: 50
nullable: true
writeOnly: true
PaginatedMeta:
description: returns the pagination information
type: object
properties:
page:
$ref: '#/components/schemas/PageMeta'
required:
- page
title: PaginatedMeta
x-speakeasy-terraform-ignore: true
StringFieldFilter:
description: 'Filter using **one** of the following operators: `eq`, `oeq`, `neq`, `contains`, `ocontains`'
type: object
properties:
eq:
description: The field exactly matches the provided value.
type: string
contains:
description: The field contains the provided value.
type: string
ocontains:
description: The field contains any of the provided values.
type: string
oeq:
description: The field matches any of the provided values.
type: string
neq:
description: The field does not match the provided value.
type: string
additionalProperties: false
CreatedAt:
description: An ISO-8601 timestamp representation of entity creation date.
type: string
format: date-time
example: '2022-11-04T20:10:06.927Z'
readOnly: true
x-speakeasy-param-suppress-computed-diff: true
BaseError:
description: standard error
type: object
properties:
status:
description: 'The HTTP status code of the error. Useful when passing the response
body to child properties in a frontend UI. Must be returned as an integer.
'
type: integer
readOnly: true
title:
description: 'A short, human-readable summary of the problem. It should not
change between occurences of a problem, except for localization.
Should be provided as "Sentence case" for direct use in the UI.
'
type: string
readOnly: true
type:
description: The error type.
type: string
readOnly: true
instance:
description: 'Used to return the correlation ID back to the user, in the format
kong:trace:<correlation_id>. This helps us find the relevant logs
when a customer reports an issue.
'
type: string
readOnly: true
detail:
description: 'A human readable explanation specific to this occurence of the problem.
This field may contain request/entity data to help the user understand
what went wrong. Enclose variable values in square brackets. Should be
provided as "Sentence case" for direct use in the UI.
'
type: string
readOnly: true
required:
- status
- title
- instance
- detail
title: Error
InvalidParameterDependentItem:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
description: invalid parameters rules
type: string
enum:
- dependent_fields
nullable: true
readOnly: true
reason:
type: string
example: is a required field
readOnly: true
dependents:
type: array
items: {}
nullable: true
readOnly: true
uniqueItems: true
source:
type: string
example: body
additionalProperties: false
required:
- field
- rule
- reason
- dependents
InvalidRules:
description: invalid parameters rules
type: string
enum:
- required
- is_array
- is_base64
- is_boolean
- is_date_time
- is_integer
- is_null
- is_number
- is_object
- is_string
- is_uuid
- is_fqdn
- is_arn
- unknown_property
- missing_reference
- is_label
- matches_regex
- invalid
- is_supported_network_availability_zone_list
- is_supported_network_cidr_block
- is_supported_provider_region
- type
nullable: true
readOnly: true
x-speakeasy-unknown-values: allow
InvalidParameters:
description: invalid parameters
type: array
items:
oneOf:
- $ref: '#/components/schemas/InvalidParameterStandard'
- $ref: '#/components/schemas/InvalidParameterMinimumLength'
- $ref: '#/components/schemas/InvalidParameterMaximumLength'
- $ref: '#/components/schemas/InvalidParameterChoiceItem'
- $ref: '#/components/schemas/InvalidParameterDependentItem'
minItems: 1
nullable: false
uniqueItems: true
BadRequestError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
required:
- invalid_parameters
properties:
invalid_parameters:
$ref: '#/components/schemas/InvalidParameters'
InvalidParameterStandard:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
$ref: '#/components/schemas/InvalidRules'
source:
type: string
example: body
reason:
type: string
example: is a required field
readOnly: true
additionalProperties: false
required:
- field
- reason
NotFoundError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 404
title:
example: Not Found
type:
example: https://httpstatuses.com/404
instance:
example: kong:trace:1234567890
detail:
example: Not found
PageMeta:
description: Contains pagination query parameters and the total number of objects returned.
type: object
properties:
number:
type: number
example: 1
x-speakeasy-terraform-ignore: true
size:
type: number
example: 10
x-speakeasy-terraform-ignore: true
total:
type: number
example: 100
x-speakeasy-terraform-ignore: true
required:
- number
- size
- total
BooleanFieldFilter:
description: Filter by a boolean value (true/false).
type: boolean
title: BooleanFieldFilter
responses:
NotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
ListPortalsResponse:
description: A paginated list of portals in the current region of an organization.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
x-speakeasy-entity: Portal
title: Portal
type: object
additionalProperties: false
properties:
id:
$ref: '#/components/schemas/UUID'
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
name:
description: The name of the portal, used to distinguish it from other portals. Name must be unique.
type: string
maxLength: 255
minLength: 1
display_name:
description: The display name of the portal. This value will be the portal's `name` in Portal API.
type: string
maxLength: 255
minLength: 1
nullable: false
description:
description: A description of the portal.
type: string
maxLength: 512
nullable: true
authentication_enabled:
description: Whether the portal supports developer authentication. If disabled, developers cannot register for accounts or create applications.
type: boolean
default: true
rbac_enabled:
description: Whether the portal resources are protected by Role Based Access Control (RBAC). If enabled, developers view or register for APIs until unless assigned to teams with access to view and consume specific APIs. Authentication must be enabled to use RBAC.
type: boolean
default: false
sipr_enabled:
description: Whether ip allow list is enabled for the portal.
type: boolean
example: true
default: false
default_api_visibility:
description: The default visibility of APIs in the portal. If set to `public`, newly published APIs are visible to unauthenticated developers. If set to `private`, newly published APIs are hidden from unauthenticated developers.
type: string
enum:
- public
- private
x-speakeasy-unknown-values: allow
default_page_visibility:
description: The default visibility of pages in the portal. If set to `public`, newly created pages are visible to unauthenticated developers. If set to `private`, newly created pages are hidden from unauthenticated developers.
type: string
enum:
- public
- private
x-speakeasy-unknown-values: allow
default_application_auth_strategy_id:
description: The default authentication strategy for APIs published to the portal. Newly published APIs will use this authentication strategy unless overridden during publication. If set to `null`, API publications will not use an authentication strategy unless set during publication.
type: string
format: uuid
nullable: true
auto_approve_developers:
description: Whether developer account registrations will be automatically approved, or if they will be set to pending until approved by an admin.
type: boolean
default: false
auto_approve_applications:
description: Whether requests from applications to register for APIs will be automatically approved, or if they will be set to pending until approved by an admin.
type: boolean
default: false
default_domain:
description: The domain assigned to the portal by Konnect. This is the default place to access the portal and its API if not using a `custom_domain``.
type: string
format: hostname
readOnly: true
canonical_domain:
description: The canonical domain of the developer portal
type: string
format: hostname
nullable: false
readOnly: true
labels:
$ref: '#/components/schemas/Labels'
required:
- id
- name
- display_name
- description
- authentication_enabled
- rbac_enabled
- sipr_enabled
- default_api_visibility
- default_page_visibility
- default_application_auth_strategy_id
- auto_approve_applications
- auto_approve_developers
- default_domain
- canonical_domain
- created_at
- updated_at
meta:
$ref: '#/components/schemas/PaginatedMeta'
additionalProperties: false
required:
- data
- meta
Conflict:
description: Conflict
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ConflictError'
Unauthorized:
description: Unauthorized
content:
application/problem+json:
schema:
description: The error response object.
type: object
properties:
status:
description: The HTTP status code.
type: integer
example: 403
title:
description: The Error Response.
type: string
example: Unauthorized
instance:
description: The Konnect traceback code.
type: string
example: konnect:trace:952172606039454040
detail:
description: Details about the error response.
type: string
example: You do not have permission to perform this action
$ref: '#/components/schemas/UnauthorizedError'
title: Unauthorized Response
PortalResponse:
description: Details about a portal.
content:
application/json:
schema:
x-speakeasy-entity: Portal
type: object
properties:
id:
$ref: '#/components/schemas/UUID'
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
name:
description: The name of the portal, used to distinguish it from other portals. Name must be unique.
type: string
maxLength: 255
minLength: 1
display_name:
description: The display name of the portal. This value will be the portal's `name` in Portal API.
type: string
maxLength: 255
minLength: 1
nullable: false
description:
description: A description of the portal.
type: string
maxLength: 512
nullable: true
authentication_enabled:
description: Whether the portal supports developer authentication. If disabled, developers cannot register for accounts or create applications.
type: boolean
default: true
rbac_enabled:
description: Whether the portal resources are protected by Role Based Access Control (RBAC). If enabled, developers view or register for APIs until unless assigned to teams with access to view and consume specific APIs. Authentication must be enabled to use RBAC.
type: boolean
default: false
sipr_enabled:
description: Whether ip allow list is enabled for the portal.
type: boolean
example: true
default: false
default_api_visibility:
description: The default visibility of APIs in the portal. If set to `public`, newly published APIs are visible to unauthenticated developers. If set to `private`, newly published APIs are hidden from unauthenticated developers.
type: string
enum:
- public
- private
x-speakeasy-unknown-values: allow
default_page_visibility:
description: The default visibility of pages in the portal. If set to `public`, newly created pages are visible to unauthenticated developers. If set to `private`, newly created pages are hidden from unauthenticated developers.
type: string
enum:
- public
- private
x-speakeasy-unknown-values: allow
default_application_auth_strategy_id:
description: The default authentication strategy for APIs published to the portal. Newly published APIs will use this authentication strategy unless overridden during publication. If set to `null`, API publications will not use an authentication strategy unless set during publication.
type: string
format: uuid
nullable: true
auto_approve_developers:
description: Whether developer account registrations will be automatically approved, or if they will be set to pending until approved by an admin.
type: boolean
default: false
auto_approve_applications:
description: Whether requests from applications to register for APIs will be automatically approved, or if they will be set to pending until approved by an admin.
type: boolean
default: false
default_domain:
description: The domain assigned to the portal by Konnect. This is the default place to access the portal and its API if not using a `custom_domain``.
type: string
format: hostname
readOnly: true
canonical_domain:
description: The canonical domain of the developer portal
type: string
format: hostname
nullable: false
readOnly: true
labels:
$ref: '#/components/schemas/Labels'
additionalProperties: false
required:
- id
- name
- display_name
- description
- authentication_enabled
- rbac_enabled
- sipr_enabled
- default_api_visibility
- default_page_visibility
- default_application_auth_strategy_id
- auto_approve_applications
- auto_approve_developers
- default_domain
- canonical_domain
- updated_at
- created_at
title: Portal
Forbidden:
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenError'
parameters:
SortPortals:
name: sort
description: "Sorts a collection of portals. Supported sort attributes are:\n - name\n - description\n - authentication_enabled\n - rbac_enabled\n - auto_approve_applications\n - auto_approve_developers\n - default_domain\n - canonical_domain\n - created_at\n - updated_at\n"
in: query
required: false
schema:
type: string
PageSize:
name: page[size]
description: The maximum number of items to include per page. The last page of a collection may include fewer items.
required: false
in: query
allowEmptyValue: true
schema:
type: integer
example: 10
x-speakeasy-terraform-ignore: true
PageNumber:
name: page[number]
description: Determines which page of the entities to retrieve.
required: false
in: query
allowEmptyValue: true
schema:
type: integer
example: 1
x-speakeasy-terraform-ignore: true
requestBodies:
UpdatePortal:
description: Update a portal's settings.
required: true
content:
application/json:
schema:
x-spe
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kong/refs/heads/main/openapi/kong-portals-api-openapi.yml