Skip to content

ptkl api-users

Manage API users, secrets, and role assignments from the command line.

Overview

API users are service accounts used for machine-to-machine authentication. They authenticate with a username and secret (instead of email and password) and are typically used in CI/CD pipelines, backend integrations, and automated scripts. ptkl api-users lets you manage their secrets, roles, and authentication tokens.

Subcommands

Subcommand Description
list List all API users
get Get an API user by UUID
edit Edit an API user's role assignments
new-secret Generate a new secret for an API user
revoke-secret Revoke an API user's current secret
get-auth-token Obtain an authentication token

ptkl api-users list

List all API users in the current project.

ptkl api-users list [options]

Options

Option Description
-f, --format <format> Output format — json or table (default: table)
-o, --output <file> Write output to a file instead of stdout

Example

ptkl api-users list
ptkl api-users list --format json

ptkl api-users get

Get the details of an API user by UUID.

ptkl api-users get [options]

Options

Option Description
-u, --uuid <uuid> UUID of the API user
-f, --format <format> Output format — json or table (default: table)
-o, --output <file> Write output to a file instead of stdout

Example

ptkl api-users get --uuid 550e8400-e29b-41d4-a716-446655440000

ptkl api-users edit

Update the role assignments of an API user.

ptkl api-users edit [options]

Options

Option Description
-u, --uuid <uuid> UUID of the API user to edit
-r, --roles <roles...> One or more role UUIDs to assign
-f, --format <format> Output format — json or table (default: table)
-o, --output <file> Write output to a file instead of stdout

Example

ptkl api-users edit \
  --uuid 550e8400-e29b-41d4-a716-446655440000 \
  --roles role-uuid-1 role-uuid-2

ptkl api-users new-secret

Generate a new secret for an API user. The new secret is printed to stdout — store it securely, as it cannot be retrieved again.

ptkl api-users new-secret [options]

Options

Option Description
-u, --uuid <uuid> UUID of the API user
-f, --format <format> Output format — json or table (default: table)
-o, --output <file> Write output to a file instead of stdout

Example

ptkl api-users new-secret --uuid 550e8400-e29b-41d4-a716-446655440000

Warning

The secret is displayed only once. Copy and store it in a secure location (e.g. a secrets manager or environment variable) immediately.

ptkl api-users revoke-secret

Revoke the current secret for an API user. Any integrations using the old secret will stop working immediately.

ptkl api-users revoke-secret [options]

Options

Option Description
-u, --uuid <uuid> UUID of the API user
-f, --format <format> Output format — json or table (default: table)
-o, --output <file> Write output to a file instead of stdout

Example

ptkl api-users revoke-secret --uuid 550e8400-e29b-41d4-a716-446655440000

ptkl api-users get-auth-token

Obtain an authentication token for an API user. Useful for scripting and CI pipelines.

ptkl api-users get-auth-token [options]

Options

Option Description
-u, --user <user> API user username
-p, --password <password> API user secret
-f, --format <format> Output format — json or table (default: table)
-o, --output <file> Write output to a file instead of stdout

Example

ptkl api-users get-auth-token --user my-service --password "$API_SECRET"

See Also