Authentication with kongctl

kongctl communicates with Konnect via the public APIs, which support token-based authentication. kongctl supports two authentication methods:

• Device Flow (recommended): Authenticate via your browser. Tokens are stored locally and refreshed automatically.
• Personal Access Token: Use the --pat flag or KONGCTL_DEFAULT_KONNECT_PAT environment variable for automation scenarios like CI/CD pipelines.

Configuration and device flow authentication credentials are stored in $XDG_CONFIG_HOME/kongctl/ (typically ~/.config/kongctl/).

Run the kongctl login command to initiate the device code authorization flow with Konnect.

kongctl login

The command will prompt you to open a URL in your browser with a one-time code to authenticate:

Logging your CLI into Kong Konnect with the browser...

 To login, go to the following URL in your browser:

   https://cloud.konghq.com/device-activate?code=KFVL-RXXJ

 Or copy this one-time code: KFVL-RXXJ

 And open your browser to https://cloud.konghq.com/device-activate

 (Code expires in 899 seconds)

 Waiting for user to Login...

After following the instructions in the browser and successfully authenticating, you will see the message User successfully authorized.

This indicates that kongctl has negotiated with Konnect and stored an access and refresh token pair for subsequent commands.

You can verify authentication by running:

kongctl get me

You should see your Konnect user information.

Now you can run kongctl commands. You’ll have access based on the permissions of the user account you logged in with.

Note: The tokens obtained using the browser-based method will expire. When they do, you can run kongctl login again to obtain new tokens.

If you want to invalidate the token received from the browser-based method, run the logout command to clear stored credentials:

kongctl logout

Konnect access tokens come in two forms: Personal Access Tokens (PAT) or System Access Tokens (sPAT). PATs grant access to APIs as your personal user account, while sPATs grant access based on the permissions of a system account, which may be more limited than a user account.

You can manage PATs and sPATs directly with kongctl. You can also create them in the Konnect UI:

• Create a PAT on the personal access token page.
• Create an sPAT on the system accounts page.

Create a PAT for the authenticated user:

kongctl create pat --name ci --expires-in 30d --output token

You must provide exactly one expiration option:

• --expires-in accepts a duration from 1 through 365 days.
• --expires-at accepts an RFC3339 timestamp from 1 through 365 days in the future.

The token value is returned only by the create operation. Store it in a secret manager immediately. get and list output contain safe token metadata and never reveal the token value.

Use the env output format to print an export command for the active profile:

kongctl create pat --name local --expires-in 7d --output env

List PAT metadata or retrieve one token record by ID or exact name:

kongctl get pat

kongctl get pat <id-or-name>

Delete a PAT:

kongctl delete pat <id-or-name> --auto-approve

Create an sPAT by selecting its system account by name:

kongctl create spat \
  --system-account-name ci-bot \
  --name deployment \
  --expires-in 30d \
  --output env

You can use --system-account-id instead of --system-account-name. sPATs have the same expiration limits and one-time secret output behavior as PATs.

List, retrieve, or delete sPAT metadata within a system account:

kongctl get spat --system-account-name ci-bot

kongctl get spat deployment --system-account-name ci-bot

kongctl delete spat deployment \
  --system-account-name ci-bot \
  --auto-approve

Configure authentication via flag

You can pass the token with each command using the --pat flag:

kongctl get apis --pat "YOUR PAT HERE"

Configure access token in environment variable

Store the token in an environment variable to avoid passing it with every command. For the default profile, set the KONGCTL_DEFAULT_KONNECT_PAT environment variable:

See the environment variable configuration reference for full details on environment variables and the kongctl configuration system.

export KONGCTL_DEFAULT_KONNECT_PAT="YOUR PAT HERE"

Then run commands normally:

kongctl get apis

Store the token in a configuration file

You can also store the token in the kongctl configuration file under the desired profile:

default:
    konnect:
        pat: "YOUR PAT HERE"

See the configuration file reference for full details on the kongctl configuration file.

Then run commands normally:

kongctl get apis

Warning: When storing tokens in configuration files, ensure the file is protected and not committed to version control. Use this method only for local development or secure environments.

Configure tokens in CI/CD

Store the token as a secret in your CI/CD platform.

For example, to store it as a secret in GitHub Actions:

- name: Deploy to Konnect
  env:
    KONGCTL_DEFAULT_KONNECT_PAT: $
  run: kongctl apply -f config/

Security: Never commit tokens to version control. Always use secrets management.