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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken

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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken

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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken

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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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:
personalAccessTokensystemAccountAccessTokenkonnectAccessToken
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": [
    ]
}