Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
    • Overview of Konnect
    • Architecture
    • Network Resiliency and Availability
    • Port and Network Requirements
    • Compatibility
    • Stages of Software Availability
    • Release Notes
      • Control Plane Upgrades FAQ
      • Supported Installation Options
    • Overview
    • Access a Konnect Account
    • Set up a Runtime
    • Configure a Service
    • Implement and Test the Service
      • Publish and Consume Services
      • Register Applications
    • Import Kong Gateway Entities into Konnect
    • Overview
      • Overview
      • Dashboard
      • Manage Runtime Groups with UI
      • Manage Runtime Groups with decK
      • Installation Options
      • Install with Docker
      • Install on Kubernetes
      • Install on Linux
      • Install on AWS
      • Install on Azure
      • Upgrade a Runtime Instance to a New Version
      • Renew Certificates
      • Runtime Parameter Reference
    • Create Consumer Groups
      • Overview
      • Set Up and Use a Vault in Konnect
    • Kong Gateway Configuration in Konnect
    • Plugin Ordering Reference
    • Troubleshoot
    • Overview
    • Manage Service Documentation
      • Overview
      • Configure a Plugin on a Service
      • Configure a Plugin on a Route
    • Overview
    • Access the Dev Portal
    • Sign Up for a Dev Portal Account
      • Manage Developer Access
      • Manage Application Registration Requests
      • Manage Application Connections
      • Auto Approve Dev and App Registrations
      • Azure OIDC
      • Application Overview
      • Enable and Disable App Registration
        • Overview
        • Okta
        • Curity
        • Auth0
      • Create, Edit, and Delete an Application
      • Register an Application with a Service
      • Generate Credentials for an Application
    • Customize Dev Portal
    • Troubleshoot
    • Introduction to Analytics
    • Analyze Services and Routes
    • Reports Use Cases
    • Reports Reference
    • Troubleshoot
      • Manage a Konnect Account or Plan
      • Change to a Different Plan
      • Manage Payment Methods and Invoices
      • Overview
        • Overview
        • Manage Teams
        • Teams Reference
        • Roles Reference
      • Manage Users
      • Manage System Accounts
      • Set up SSO with OIDC
      • Set up SSO with Okta
      • Login Sessions Reference
    • Account and Org Deactivation
    • Troubleshoot
    • Overview
      • API Documentation
      • Identity Integration Guide
      • API Documentation
      • API Documentation
      • Portal RBAC Guide
      • Overview
      • Nodes
      • Data Plane Certificiates
        • Services
        • Routes
        • Consumers
        • Plugins
        • Upstreams
        • Certificates
        • CA Certificates
        • SNIs
        • Targets
        • Vaults
      • API Spec
      • Filtering
    • Labels

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Manage a system account via the UI
  • Manage a system account via the API
    • Create a system account
    • Generate a system account access token
    • Assign a role to a system account
    • Assign a system account to a team
  • See also
Kong Konnect
  • Home
  • Kong Konnect
  • Org Management
  • Manage System Accounts

Manage System Accounts

This guide explains what a system account is, how it varies from a user account, and how to manage a system account using the Konnect Identity API.

A system account is a service account in Konnect. Because system accounts are not associated with an email address and a user, they can be used for automation and integrations.

System accounts offer the following benefits over regular user accounts:

  • System accounts are not associated with an email address. This allows you to use the account as part of an automation or integration that isn’t associated with any person’s identity.
  • When you use a user account as part of an automation or integration and that user leaves the company, automation and integrations break. If you use a system account instead, the automation and integrations wouldn’t break.
  • System accounts don’t have sign-in credentials and therefore can’t access the Konnect UI. These accounts are intended to be used with APIs and CLIs.

The system account can use a Konnect personal access token (PAT) the same way a regular Konnect user can. In addition, the system account can be assigned roles directly or inherit the roles of a team. As such, a PAT created by a system account inherits the roles assigned to the system account.

Manage a system account via the UI

You can create and manage system accounts in your Konnect organization through the organizations icon Organization > System Accounts page.

From the System Accounts page, you can:

  • Create and manage system accounts.
  • Create and manage system account access tokens.
  • Assign roles to a system account.
  • Manage team memberships for a system account.

Manage a system account via the API

Create a system account

Create a system account by sending a POST request containing the name of your system account in the response body:

curl --request POST \
  --url https://global.api.konghq.com/v2/system-accounts
  --data '{
  "name": "Example System Account"}'

You will receive a 201 response code, and a response body containing information about your system account:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "Example System Account",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Generate a system account access token

The system account access token can be used for authenticating API and CLI requests.

Create a system account token by sending a POST request containing the accountId of the system account:

curl --request POST \
  --url https://global.api.konghq.com/v2/system-accounts/:497f6eca-6276-4993-bfeb-53cbbbba6f08/access-tokens

You will receive a 201 response code, and a response body containing the access token for the system account:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "Sample Access Token",
  "created_at": "2023-01-12:15:54Z",
  "expires_at": "2023-11-15T00:00:00Z",
  "updated_at": "2023-01-13T21:04:22Z",
  "last_used_at": "2023-01-18T06:45:40Z",
  "token": "spat_12345678901234567890123456789012345678901234567890"
}

Copy and save the access token beginning with spat_.

Important: The access token is only displayed once, so make sure you save it securely.

Assign a role to a system account

You can assign a role to a system account so that the permissions associated with that role can be assigned to that account and their subsequent credentials.

Assign a role to a system account by sending a POST request containing the accountId and the role_name of the system account:

curl --request POST \
  --url https://global.api.konghq.com/v2/system-accounts/:497f6eca-6276-4993-bfeb-53cbbbba6f08/assigned-roles
  --data '{
  "role_name": "Viewer",
  "entity_id": "817d0422-45c9-4d88-8d64-45aef05c1ae7",
  "entity_type_name": "Runtime Groups",
  "entity_region": "eu"
}'

You will receive a 201 response code and a response body containing the role that is now assigned to the system account:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "role_name": "Viewer",
  "entity_id": "817d0422-45c9-4d88-8d64-45aef05c1ae7",
  "entity_type_name": "Runtime Groups",
  "entity_region": "eu"
}

Assign a system account to a team

You can assign a team to a system account so that the permissions associated with that team can be assigned to that account and their subsequent credentials.

Assign a team to a system account by sending a POST request containing the teamId of the team:

curl --request POST \
  --url https://global.api.konghq.com/v2/teams/:497f6eca-6276-4993-bfeb-53cbbbba6f08/system-accounts

You will receive a 201 response code and a response body stating that the system account was added to the team:

Created

See also

See the following documentation for additional information:

  • Manage Teams and Roles
  • Roles Reference
  • Teams Reference
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023