API docs by Redocly

Konnect Identity Management (2.0.0)

Download OpenAPI specification:Download

URL: https://konghq.com

The management API for Kong Konnect Identity resources.

Auth Settings

Get Auth Settings

Returns authentication configuration, which determines how users can log in and how they are assigned to teams.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken

Responses

Response samples

Content type
application/json
{
  • "oidc_auth_enabled": true,
  • "saml_auth_enabled": false,
  • "basic_auth_enabled": false,
  • "idp_mapping_enabled": false,
  • "konnect_mapping_enabled": true
}

Update Auth Settings

Updates authentication configuration.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema to update an organization's authentication settings.

basic_auth_enabled
boolean

The organization has basic auth enabled.

oidc_auth_enabled
boolean

The organization has OIDC disabled.

saml_auth_enabled
boolean

The organization has SAML disabled.

idp_mapping_enabled
boolean

Whether IdP groups determine the Konnect teams a user has.

konnect_mapping_enabled
boolean

Whether a Konnect Identity Admin assigns teams to a user.

Responses

Request samples

Content type
application/json
{
  • "oidc_auth_enabled": false,
  • "saml_auth_enabled": false,
  • "basic_auth_enabled": true,
  • "idp_mapping_enabled": false,
  • "konnect_mapping_enabled": true
}

Response samples

Content type
application/json
{
  • "oidc_auth_enabled": true,
  • "saml_auth_enabled": false,
  • "basic_auth_enabled": false,
  • "idp_mapping_enabled": false,
  • "konnect_mapping_enabled": true
}

Fetch IdP Configuration

Fetch the IdP configuration.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken

Responses

Response samples

Content type
application/json
{
  • "issuer": "https://myidp.com/oauth2",
  • "login_path": "myapp",
  • "client_id": "YOUR_CLIENT_ID",
  • "scopes": [
    ],
  • "claim_mappings": {
    }
}

Update IdP Configuration

Update the IdP configuration.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema for the update IdP configuration request.

issuer
string <uri>
login_path
string
client_id
string
client_secret
string
scopes
Array of strings
Default: ["email","openid","profile"]
object >= 3 properties

Responses

Request samples

Content type
application/json
{
  • "issuer": "https://myidp.com/oauth2",
  • "login_path": "myapp",
  • "client_id": "YOUR_CLIENT_ID",
  • "client_secret": "YOUR_CLIENT_SECRET",
  • "scopes": [
    ],
  • "claim_mappings": {
    }
}

Response samples

Content type
application/json
{
  • "issuer": "https://myidp.com/oauth2",
  • "login_path": "myapp",
  • "client_id": "YOUR_CLIENT_ID",
  • "scopes": [
    ],
  • "claim_mappings": {
    }
}

Update Team Mappings

Updates the IdP group to Konnect team mapping.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema for updating IdP team mappings.

Array of objects

The mappings object.

Responses

Request samples

Content type
application/json
{
  • "mappings": [
    ]
}

Response samples

Content type
application/json
{
  • "mappings": [
    ]
}

Fetch Team Mapping

Fetch the IdP group to Konnect team mapping.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Fetch Team Group Mappings

Retrieves the mappings between Konnect Teams and Identity Provider Groups. Returns a 400 error if an Identity Provider has not yet been configured.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

Responses

Response samples

Content type
application/json
{
  • "mappings": [
    ]
}

Patch Mappings by Team ID

Allows partial updates to the mappings between Konnect Teams and Identity Provider Groups. The request body must be keyed on team ID. For a given team ID, the given group list is a complete replacement. To remove all mappings for a given team, provide an empty group list.

Returns a 400 error if an Identity Provider has not yet been configured, or if a team ID in the request body is not found or is not a UUID.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema for a partial update of mappings from Konnect Teams to IdP Groups.

Array of objects

The IdP groups to map to the given team.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "mappings": [
    ]
}

Invites

Accept Invite

Accepts the Konnect invitation. This endpoint allows you to manually accept the invitation to join a Konnect organization. Upon accepting the invitation, the user's name and password are set and the active state is set to true. This can be used as an alternative to the https://cloud.konghq.com/login link in the email which will finish the registration process in a web browser.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema for the accept invite request.

password
required
string <password>

Sets the password for the user.

full_name
required
string

Full name of the user.

preferred_name
string or null

Preferred name of the user.

token
required
string <uuid>

The one time token in accept-invitation link.

Responses

Request samples

Content type
application/json
{
  • "password": "TestPassword123!!",
  • "full_name": "James C. Woods",
  • "preferred_name": "Tiger",
  • "token": "7690d649-86fc-4d10-8771-c094d2efbd85"
}

Response samples

Content type
application/problem+json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "instance": "konnect:trace:3674017986744198214",
  • "invalid_parameters": [
    ]
}

Invite User

Sends an invitation email to invite a user to the Konnect organization. The email contains a link with a one time token to accept the invitation. Upon accepting the invitation, the user is directed to https://cloud.konghq.com/login to complete registration.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema for the invite user request.

If you pass an email that is not already an active user in the request, a fresh invitation email will be created and sent to the new user.

email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "james.c.woods@example.com"
}

Response samples

Content type
application/problem+json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "instance": "konnect:trace:3674017986744198214",
  • "invalid_parameters": [
    ]
}

Roles

Get Predefined Roles

Retrieves the predefined, or system managed, roles.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken

Responses

Response samples

Content type
application/json
{
  • "runtime_groups": {
    },
  • "services": {
    },
  • "audit_logs": {
    },
  • "identity": {
    },
  • "mesh_control_planes": {
    }
}

List Team Roles

Lists the roles belonging to a team.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string <uuid>
Example: e81bc3e5-e9db-4764-b7dd-e81e39072cbe

The team ID

query Parameters
object

Filter roles returned in the response. Returns 400 if any filter parameters are invalid.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Assign Role

Assigns a role to a team. Returns 409 if role is already assigned.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string <uuid>
Example: e81bc3e5-e9db-4764-b7dd-e81e39072cbe

The team ID

Request Body schema: application/json

The request schema for assigning a role.

role_name
string

The desired role.

entity_id
string <uuid>

The ID of the entity.

entity_type_name
string

The type of entity.

entity_region
string
Enum: "us" "eu" "au" "me" "in" "*"

The region of the team.

Responses

Request samples

Content type
application/json
Example
{
  • "role_name": "Viewer",
  • "entity_id": "18ee2573-dec0-4b83-be99-fa7700bcdc61",
  • "entity_type_name": "Runtime Groups",
  • "entity_region": "us"
}

Response samples

Content type
application/json
{
  • "id": "eaf7adf1-32c8-4bbf-b960-d1f8456afe67",
  • "role_name": "Viewer",
  • "entity_id": "817d0422-45c9-4d88-8d64-45aef05c1ae7",
  • "entity_type_name": "Runtime Groups",
  • "entity_region": "eu"
}

Remove Role

Removes an assigned role from a team. Returns 404 if the requested team or assigned role were not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string <uuid>
Example: e81bc3e5-e9db-4764-b7dd-e81e39072cbe

The team ID.

roleId
required
string <uuid>
Example: 8350205f-a305-4e39-abe9-bc082a80091a

The role ID.

Responses

Response samples

Content type
application/problem+json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "instance": "konnect:trace:3674017986744198214",
  • "invalid_parameters": [
    ]
}

List User Roles

Lists the roles assigned to a user. Returns 400 if any filter parameters are invalid.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
userId
required
string <uuid>
Example: e81bc3e5-e9db-4764-b7dd-e81e39072cbe

The user ID

query Parameters
object

Filter roles returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Assign Role

Assigns a role to a user. Returns 409 if role is already assigned.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
userId
required
string <uuid>
Example: e81bc3e5-e9db-4764-b7dd-e81e39072cbe

The user ID

Request Body schema: application/json

The request schema for assigning a role.

role_name
string

The desired role.

entity_id
string <uuid>

The ID of the entity.

entity_type_name
string

The type of entity.

entity_region
string
Enum: "us" "eu" "au" "me" "in" "*"

The region of the team.

Responses

Request samples

Content type
application/json
Example
{
  • "role_name": "Viewer",
  • "entity_id": "18ee2573-dec0-4b83-be99-fa7700bcdc61",
  • "entity_type_name": "Runtime Groups",
  • "entity_region": "us"
}

Response samples

Content type
application/json
{
  • "id": "eaf7adf1-32c8-4bbf-b960-d1f8456afe67",
  • "role_name": "Viewer",
  • "entity_id": "817d0422-45c9-4d88-8d64-45aef05c1ae7",
  • "entity_type_name": "Runtime Groups",
  • "entity_region": "eu"
}

Remove Role

Removes an assigned role from a user. Returns 404 if the requested user or assigned role were not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
userId
required
string <uuid>
Example: e81bc3e5-e9db-4764-b7dd-e81e39072cbe

ID of the user.

roleId
required
string <uuid>
Example: 8350205f-a305-4e39-abe9-bc082a80091a

ID of the role.

Responses

Response samples

Content type
application/problem+json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "instance": "konnect:trace:3674017986744198214",
  • "invalid_parameters": [
    ]
}

Team Membership

List Team Users

Returns a paginated list of users that belong to the team specified in the path parameter.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

ID of the team.

query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

object

Filter users returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Add User

Adds a user to a team.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

ID of the team.

Request Body schema: application/json

The request schema for adding a user to a team.

id
required
string <uuid>

The user ID for the user being added to a team.

Responses

Request samples

Content type
application/json
{
  • "id": "df120cb4-f60b-47bc-a2f8-6a28e6a3c63b"
}

Response samples

Content type
application/problem+json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "instance": "konnect:trace:3674017986744198214",
  • "invalid_parameters": [
    ]
}

Remove User

Removes a user from a team. If the user was removed, returns a 204 empty response. Returns 404 if the user or team were not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
userId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

User ID

teamId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

Team ID.

Responses

Response samples

Content type
application/problem+json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "instance": "konnect:trace:3674017986744198214",
  • "invalid_parameters": [
    ]
}

List User Teams

Returns a paginated list of a teams that the user belongs to.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
userId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

The user ID.

query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

object

Filter teams returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Teams

List Teams

Returns an array of team objects containing information about the Konnect Teams.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

object

Filter teams returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create Team

Creates a team in the Konnect Organization.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema for the create team request.

If you pass the same name and description of an existing team in the request, a team with the same name and description will be created. The two teams will have different team_id values to differentiate them.

name
required
string^[\w \W]+$

A name for the team being created.

description
string <= 250 characters

The description of the new team.

Responses

Request samples

Content type
application/json
{
  • "name": "IDM - Developers",
  • "description": "The Identity Management (IDM) team."
}

Response samples

Content type
application/json
{
  • "id": "7f9fd312-a987-4628-b4c5-bb4f4fddd5f7",
  • "name": "IDM - Developers",
  • "description": "The developers for the IDM API.",
  • "system_team": false,
  • "created_at": "2022-02-07T17:46:57.52Z",
  • "updated_at": "2022-09-25T13:00:00.00Z"
}

Fetch Team

Returns information about a team from a given team ID.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

The team ID

Responses

Response samples

Content type
application/json
{
  • "id": "7f9fd312-a987-4628-b4c5-bb4f4fddd5f7",
  • "name": "IDM - Developers",
  • "description": "The developers for the IDM API.",
  • "system_team": false,
  • "created_at": "2022-02-07T17:46:57.52Z",
  • "updated_at": "2022-09-25T13:00:00.00Z"
}

Update Team

Updates an individual team.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

The team ID

Request Body schema: application/json

The request schema for the update team request.

name
string^[\w \W]+$

The name of the team.

description
string <= 250 characters

The description of the team.

Responses

Request samples

Content type
application/json
{
  • "name": "IDM - Developers",
  • "description": "The Identity Management (IDM) API team."
}

Response samples

Content type
application/json
{
  • "id": "7f9fd312-a987-4628-b4c5-bb4f4fddd5f7",
  • "name": "IDM - Developers",
  • "description": "The developers for the IDM API.",
  • "system_team": false,
  • "created_at": "2022-02-07T17:46:57.52Z",
  • "updated_at": "2022-09-25T13:00:00.00Z"
}

Delete Team

Deletes an individual team. Returns 404 if the team is not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

The team ID

Responses

Response samples

Content type
application/problem+json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "instance": "konnect:trace:3674017986744198214",
  • "invalid_parameters": [
    ]
}

Users

List Users

Returns a paginated list of user objects.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

object

Filter users returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Fetch User

Returns the user object for the user ID specified as a path parameter.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
userId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

The ID of the user being deleted.

Responses

Response samples

Content type
application/json
{
  • "id": "7f9fd312-a987-4628-b4c5-bb4f4fddd5f7",
  • "email": "james.woods@email.com",
  • "full_name": "James Woods",
  • "preferred_name": "Jimmy",
  • "active": true,
  • "created_at": "1992-02-07T17:46:57.52Z",
  • "updated_at": "2022-02-07T17:00:00.52Z"
}

Update User

Update an individual user.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
userId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

The ID of the user being deleted.

Request Body schema: application/json

The request schema for the update user request.

full_name
string^[\w \W]+$

The user's full name.

preferred_name
string <= 250 characters

The user's desired name.

Responses

Request samples

Content type
application/json
{
  • "full_name": "James C Woods",
  • "preferred_name": "Jimmy"
}

Response samples

Content type
application/json
{
  • "id": "7f9fd312-a987-4628-b4c5-bb4f4fddd5f7",
  • "email": "james.woods@email.com",
  • "full_name": "James Woods",
  • "preferred_name": "Jimmy",
  • "active": true,
  • "created_at": "1992-02-07T17:46:57.52Z",
  • "updated_at": "2022-02-07T17:00:00.52Z"
}

Delete User

Deletes an individual user. Returns 404 if the requested user was not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
userId
required
string <uuid>
Example: d32d905a-ed33-46a3-a093-d8f536af9a8a

The ID of the user being deleted.

Responses

Response samples

Content type
application/problem+json
{
  • "status": 404,
  • "title": "Not Found",
  • "instance": "konnect:trace:2287285207635123011",
  • "detail": "The requested team was not found"
}

System Accounts

List System Accounts

Returns an array of system accounts (SA) in the organization. Returns 400 if any filter parameters are invalid.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

object

Filter system accounts returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create System Account

Creates a system account. Returns a 409 if a system account with the same name already exists.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema to create a system account.

name
required
string

Name of the system account.

description
required
string

Description of the system account. Useful when the system account name is not sufficient to differentiate one system account from another.

konnect_managed
boolean

The system account is managed by Konnect (true/false).

Responses

Request samples

Content type
application/json
{
  • "name": "Sample System Account",
  • "description": "This is a sample system account description.",
  • "konnect_managed": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Sample System Account",
  • "description": "This is a sample system account description.",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "konnect_managed": false
}

Fetch System Account

Returns the system account (SA) for the SA ID specified as a path parameter.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Sample System Account",
  • "description": "This is a sample system account description.",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "konnect_managed": false
}

Update System Account

Updates the specified system account. Returns a 409 if the updated name is the same as another system account in the organization.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

Request Body schema: application/json

The request schema for the update system account request.

name
string

Name of the system account.

description
string

Description of the system account.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Sample System Account",
  • "description": "This is a sample system account description.",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "konnect_managed": false
}

Delete System Account

Deletes the specified system account. Returns 404 if the requested account was not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

Responses

Response samples

Content type
application/problem+json
{
  • "status": 401,
  • "title": "Unauthenticated",
  • "instance": "konnect:trace:952172606039454040",
  • "detail": "A valid token is required"
}

System Accounts - Access Tokens

List System Account Access Tokens

Returns the access tokens for the specified system account. Returns 400 if any filter parameters are invalid.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

object

Filter access tokens returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create System Account Access Token

Creates an access token for the specified system account (SA). The access token can be used for authenticating API and CLI requests. The token will only be displayed once on creation. Returns a 409 if the system account already has a token with the same name.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

Request Body schema: application/json

The request body to create a system account access token.

name
string
expires_at
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Access Token",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Sample Access Token",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "token": "npat_12345678901234567890123456789012345678901234567890"
}

Fetch System Account Access Token

Returns the system account (SA) access token for the SA Access Token ID specified as a path parameter.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

tokenId
required
string

ID of the system account access token.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Sample Access Token",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z"
}

Update System Account Access Token

Updates the specified access token. Returns a 409 if the updated name is the same as another token belonging to the specified system user.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

tokenId
required
string

ID of the system account access token.

Request Body schema: application/json
name
string

Name of the system account access token.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Sample Access Token",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z"
}

Delete System Account Access Token

Deletes the specified token. Returns 404 if the token was not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

tokenId
required
string

ID of the system account access token.

Responses

Response samples

Content type
application/problem+json
{
  • "status": 401,
  • "title": "Unauthenticated",
  • "instance": "konnect:trace:952172606039454040",
  • "detail": "A valid token is required"
}

System Accounts - Roles

Fetch Assigned Roles for System Account

Lists the roles belonging to a system account. Returns 400 if any filter parameters are invalid.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

query Parameters
object

Filter roles returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create Assigned Role for System Account

Assigns a role to a system account. Returns 409 if role is already assigned.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

Request Body schema: application/json

The request schema for assigning a role.

role_name
string

The desired role.

entity_id
string <uuid>

The ID of the entity.

entity_type_name
string

The type of entity.

entity_region
string
Enum: "us" "eu" "au" "me" "in" "*"

The region of the team.

Responses

Request samples

Content type
application/json
Example
{
  • "role_name": "Viewer",
  • "entity_id": "18ee2573-dec0-4b83-be99-fa7700bcdc61",
  • "entity_type_name": "Runtime Groups",
  • "entity_region": "us"
}

Response samples

Content type
application/json
{
  • "id": "eaf7adf1-32c8-4bbf-b960-d1f8456afe67",
  • "role_name": "Viewer",
  • "entity_id": "817d0422-45c9-4d88-8d64-45aef05c1ae7",
  • "entity_type_name": "Runtime Groups",
  • "entity_region": "eu"
}

Delete Assigned Role from System Account

Removes an assigned role from a system account. Returns 404 if the system account or assigned role were not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

roleId
required
string

ID of the role.

Responses

Response samples

Content type
application/problem+json
{
  • "status": 401,
  • "title": "Unauthenticated",
  • "instance": "konnect:trace:952172606039454040",
  • "detail": "A valid token is required"
}

System Accounts - Team Membership

List System Accounts on a Team

Returns a paginated list of system accounts that belong to the team specified in the path parameter.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string

ID of the team.

query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

object

Filter system accounts returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Add System Account to a Team

Adds a system account to a team. Returns a 409 if the system account is already a member of the team.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string

ID of the team.

Request Body schema: application/json

The request schema for adding a system account to a team.

id
string <uuid>

ID of the system account.

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Response samples

Content type
application/problem+json
{
  • "status": 401,
  • "title": "Unauthenticated",
  • "instance": "konnect:trace:952172606039454040",
  • "detail": "A valid token is required"
}

Remove System Account From Team

Removes a system account from a team. Returns 404 if the team or system account were not found.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
teamId
required
string

ID of the team.

accountId
required
string

ID of the system account.

Responses

Response samples

Content type
application/problem+json
{
  • "status": 401,
  • "title": "Unauthenticated",
  • "instance": "konnect:trace:952172606039454040",
  • "detail": "A valid token is required"
}

List Teams for a System Account

Returns a paginated list of a teams that the system account belongs to.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
path Parameters
accountId
required
string

ID of the system account.

query Parameters
page[size]
integer
Example: page[size]=10

The maximum number of items to include per page. The last page of a collection may include fewer items.

page[number]
integer
Example: page[number]=1

Determines which page of the entities to retrieve.

object

Filter teams returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Me

Retrieve My User Account

Returns the user account for the user identified in the token of the request.

Authorizations:
personalAccessTokenkonnectAccessToken

Responses

Response samples

Content type
application/json
{
  • "id": "7f9fd312-a987-4628-b4c5-bb4f4fddd5f7",
  • "email": "james.woods@email.com",
  • "full_name": "James Woods",
  • "preferred_name": "Jimmy",
  • "active": true,
  • "created_at": "1992-02-07T17:46:57.52Z",
  • "updated_at": "2022-02-07T17:00:00.52Z"
}

Delete My User Account

Deletes the user account for the user identified in the token of the request.

Authorizations:
konnectAccessToken

Responses

Response samples

Content type
application/problem+json
{
  • "status": 401,
  • "title": "Unauthenticated",
  • "instance": "konnect:trace:952172606039454040",
  • "detail": "A valid token is required"
}

Update My User Account

Updates the user account for the user identified in the token of the request.

Authorizations:
konnectAccessToken
Request Body schema: application/json

The request schema for the update user request.

full_name
string^[\w \W]+$

The user's full name.

preferred_name
string <= 250 characters

The user's desired name.

Responses

Request samples

Content type
application/json
{
  • "full_name": "James C Woods",
  • "preferred_name": "Jimmy"
}

Response samples

Content type
application/json
{
  • "id": "7f9fd312-a987-4628-b4c5-bb4f4fddd5f7",
  • "email": "james.woods@email.com",
  • "full_name": "James Woods",
  • "preferred_name": "Jimmy",
  • "active": true,
  • "created_at": "1992-02-07T17:46:57.52Z",
  • "updated_at": "2022-02-07T17:00:00.52Z"
}

Update My User Account Password

Update the password of the user identified in the token of the request.

Authorizations:
konnectAccessToken
Request Body schema: application/json
old_password
required
string

Old password.

new_password
required
string

New Password.

Responses

Request samples

Content type
application/json
{
  • "old_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/problem+json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "instance": "konnect:trace:3674017986744198214",
  • "invalid_parameters": [
    ]
}

Get My Permissions

Returns the permissions for the current user

Authorizations:
konnectAccessToken
query Parameters
object

Filter permissions returned in the response.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve My Organization

Returns the organization of the user identified in the token of the request.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-01-18T11:35:45.130Z",
  • "id": "023bfa42-3513-4cbf-b059-a9ddb4ea995d",
  • "name": "Acme Co.",
  • "owner_id": "e02c829c-0e2d-44b5-9057-07714ea613a3",
  • "login_path": "acme",
  • "updated_at": "2023-01-23T17:22:52.150Z",
  • "state": "active",
  • "retention_period_days": 90
}

Updates the current user's organization

This operation allows you to change the organization's owner. The new user must be part of the organization's admin team.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json

The request schema to update an organization.

owner_id
string

The user id of the new owner of the organization. Must be a member of the organization's admin team.

name
string

The new name of the organization.

Responses

Request samples

Content type
application/json
{
  • "owner_id": "df120cb4-f60b-47bc-a2f8-6a28e6a3c63b",
  • "name": "Kong Inc"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-01-18T11:35:45.130Z",
  • "id": "023bfa42-3513-4cbf-b059-a9ddb4ea995d",
  • "name": "Acme Co.",
  • "owner_id": "e02c829c-0e2d-44b5-9057-07714ea613a3",
  • "login_path": "acme",
  • "updated_at": "2023-01-23T17:22:52.150Z",
  • "state": "active",
  • "retention_period_days": 90
}

Managed System Accounts - Roles

Fetch assigned roles for a managed system account. Returns 400 if any filter parameters are invalid.

Lists the roles belonging to a managed system account.

Authorizations:
clientToken
path Parameters
accountId
required
string

ID of the system account.

query Parameters
object

Filter roles returned in the response.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Assign a role to a managed System Account.

Assigns a role to a managed system account. Returns 409 if role is already assigned.

Authorizations:
clientToken
path Parameters
accountId
required
string

ID of the system account.

Request Body schema: application/json

The request schema for assigning a role.

role_name
string

The desired role.

entity_id
string <uuid>

The ID of the entity.

entity_type_name
string

The type of entity.

entity_region
string
Enum: "us" "eu" "au" "me" "in" "*"

The region to scope the role assignment to.

parameters
object

Responses

Request samples

Content type
application/json
{
  • "id": "eaf7adf1-32c8-4bbf-b960-d1f8456afe67",
  • "role_name": "Connector",
  • "entity_id": "18ee2573-dec0-4b83-be99-fa7700bcdc61",
  • "entity_type_name": "Mesh Control Planes",
  • "entity_region": "eu",
  • "parameters": {
    }
}

Response samples

Content type
application/json
{
  • "id": "eaf7adf1-32c8-4bbf-b960-d1f8456afe67",
  • "role_name": "Connector",
  • "entity_id": "18ee2573-dec0-4b83-be99-fa7700bcdc61",
  • "entity_type_name": "Mesh Control Planes",
  • "entity_region": "eu",
  • "parameters": {
    }
}

SSO Auth0

Register a new organization with an Auth0 authenticated user.

Create a new organization with Auth0 authentication. The Auth0 user will be the organization owner.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken
Request Body schema: application/json
organization_name
required
string
default_region
required
string

Responses

Request samples

Content type
application/json
{
  • "organization_name": "string",
  • "default_region": "string"
}

Response samples

Content type
application/json
{
  • "organization_id": "string",
  • "login_path": "string"
}

Retrieves the list of organizations available to the given user.

Retrieves the list of organizations available to the given user.

Authorizations:
personalAccessTokensystemAccountAccessTokenkonnectAccessTokenclientToken

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}