kms login

kms login

Description

Feedback
Browser Login (default): Opens a browser for authentication
Feedback
Direct Login: Provide email and password via flags or environment variables for non-interactive workflows
Feedback
Interactive CLI Login: Use the --interactive flag to enter credentials via CLI prompts

JWT Token Output:

• For user authentication with the --plain --silent flags: outputs only the JWT access token (useful for scripting)
• For machine identity authentication: an access token is always printed to the console

Use the --plain flag to print only the token in plain text and the --silent flag to disable update alerts.

Both flags are ideal for capturing the token in environment variables or CI/CD pipelines.

Authentication Methods

User Authentication

The User authentication method allows you to log in with your email and password. This method supports three different login flows:

• Browser Login (default): Opens a browser for authentication
• Direct Login: Provide credentials via flags or environment variables for CI/CD
• Interactive CLI Login: Enter credentials via CLI prompts using --interactive

Your email address. Required for direct login along with --password and --organization-id.

Your password. Required for direct login along with --email and --organization-id.

Your organization id. Required for direct login along with --password and --email.

Force interactive CLI login instead of browser-based authentication.

Output only the JWT token (useful for scripting and CI/CD).

kms login

kms login --email=user@example.com --password=your-password --organization-id=your-organization-id

# Or using environment variables
export INFISICAL_EMAIL="user@example.com"
export INFISICAL_PASSWORD="your-password"
export INFISICAL_ORGANIZATION_ID="your-organization-id"
kms login

kms login --interactive

export INFISICAL_TOKEN=$(kms login --email=user@example.com --password=your-password --organization-id=your-organization-id --plain --silent)

Machine Identity Authentication

The Universal Auth method is a simple and secure way to authenticate with Hanzo KMS. It requires a client ID and a client secret to authenticate with Hanzo KMS.

Your machine identity client ID.

Your machine identity client secret.

To create a universal auth machine identity, follow the step by step guide outlined here.

Run the login command with the following flags to obtain an access token:

  kms login --method=universal-auth --client-id=<client-id> --client-secret=<client-secret>

The Native Kubernetes method is used to authenticate with Hanzo KMS when running in a Kubernetes environment. It requires a service account token to authenticate with Hanzo KMS.

Your machine identity ID.

Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

To create a Kubernetes machine identity, follow the step by step guide outlined here.

Run the login command with the following flags to obtain an access token:

  # --service-account-token-path is optional, and will default to '/var/run/secrets/kubernetes.io/serviceaccount/token' if not provided.
  kms login --method=kubernetes --machine-identity-id=<machine-identity-id> --service-account-token-path=<service-account-token-path>

The Native Azure method is used to authenticate with Hanzo KMS when running in an Azure environment.

Your machine identity ID.

To create an Azure machine identity, follow the step by step guide outlined here.

Run the login command with the following flags to obtain an access token:

  kms login --method=azure --machine-identity-id=<machine-identity-id>

The Native GCP ID Token method is used to authenticate with Hanzo KMS when running in a GCP environment.

Your machine identity ID.

To create a GCP machine identity, follow the step by step guide outlined here.

Run the login command with the following flags to obtain an access token:

  kms login --method=gcp-id-token --machine-identity-id=<machine-identity-id>

The GCP IAM method is used to authenticate with Hanzo KMS with a GCP service account key.

Your machine identity ID.

Path to your GCP service account key file (Must be in JSON format!)

To create a GCP machine identity, follow the step by step guide outlined here.

Run the login command with the following flags to obtain an access token:

  kms login --method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path>

The AWS IAM method is used to authenticate with Hanzo KMS with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.

Your machine identity ID.

To create an AWS machine identity, follow the step by step guide outlined here.

Run the login command with the following flags to obtain an access token:

  kms login --method=aws-iam --machine-identity-id=<machine-identity-id>

The OIDC Auth method is used to authenticate with Hanzo KMS via identity tokens with OIDC.

Your machine identity ID.

The OIDC JWT from the identity provider.

To create an OIDC machine identity, follow the step by step guide outlined here.

Run the login command with the following flags to obtain an access token:

  kms login --method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt>

The JWT Auth method is used to authenticate with Hanzo KMS via a JWT token.

The JWT token to use for authentication.

Your machine identity ID.

Run the login command with the following flags to obtain an access token:

  kms login --method=jwt-auth --jwt=<jwt-token> --machine-identity-id=<machine-identity-id>

Flags

kms login --method=<auth-method> # Optional, will default to 'user'.

Valid values for the method flag are:

• user: Login using email and password. (default)
• universal-auth: Login using a universal auth client ID and client secret.
• kubernetes: Login using a Kubernetes native auth.
• azure: Login using an Azure native auth.
• gcp-id-token: Login using a GCP ID token native auth.
• gcp-iam: Login using a GCP IAM.
• aws-iam: Login using an AWS IAM native auth.
• oidc-auth: Login using OIDC auth.
• jwt-auth: Login using a plain JWT token.

kms login --method=<auth-method> --organization-slug="team2" 

Description

This authenticates the machine identity against the specified sub-organization.

The organization-slug flag can be substituted with the INFISICAL_AUTH_ORGANIZATION_SLUG environment variable.

If no organization slug is provided, the authentication session defaults to the organization where the machine identity was originally created.

kms login --client-id=<client-id> # Optional, required if --method=universal-auth.

Description

The client ID of the universal auth machine identity. This is required if the --method flag is set to universal-auth.

The client-id flag can be substituted with the INFISICAL_UNIVERSAL_AUTH_CLIENT_ID environment variable.

kms login --client-secret=<client-secret> # Optional, required if --method=universal-auth.

Description

The client secret of the universal auth machine identity. This is required if the --method flag is set to universal-auth.

The client-secret flag can be substituted with the INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET environment variable.

kms login --machine-identity-id=<your-machine-identity-id> # Optional, required if --method=kubernetes, azure, gcp-id-token, gcp-iam, or aws-iam.

Description

The ID of the machine identity. This is required if the --method flag is set to kubernetes, azure, gcp-id-token, gcp-iam, or aws-iam.

The machine-identity-id flag can be substituted with the INFISICAL_MACHINE_IDENTITY_ID environment variable.

kms login --service-account-token-path=<service-account-token-path> # Optional Will default to '/var/run/secrets/kubernetes.io/serviceaccount/token'.

Description

The path to the Kubernetes service account token to use for authentication. This is optional and will default to /var/run/secrets/kubernetes.io/serviceaccount/token.

The service-account-token-path flag can be substituted with the INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH environment variable.

kms login --service-account-key-file-path=<gcp-service-account-key-file-path> # Optional, but required if --method=gcp-iam.

Description

The path to your GCP service account key file. This is required if the --method flag is set to gcp-iam.

The service-account-key-path flag can be substituted with the INFISICAL_GCP_IAM_SERVICE_ACCOUNT_KEY_FILE_PATH environment variable.

kms login --email=<email> --password=<password> --organization-id=<organization-id>

Description

User email address. Required if you want to do a non-interactive login when the --method flag is set to user. Must be used together with the --password and --organization-id flag.

You can omit the --method=user if you want as it's the default method.

The email flag can be substituted with the INFISICAL_EMAIL environment variable.

kms login --email=<email> --password=<password> --organization-id=<organization-id>

Description

User password. Required if you want to do a non-interactive login when the --method flag is set to user. Must be used together with the --email and --organization-id flag.

For security in CI/CD environments, prefer using the INFISICAL_PASSWORD environment variable instead of passing the password as a command-line flag.

You can omit the --method=user if you want as it's the default method.

The password flag can be substituted with the INFISICAL_PASSWORD environment variable.

kms login --email=<email> --password=<password> --organization-id=<organization-id>

Description

User organization id. Required if you want to do a non-interactive login when the --method flag is set to user. Must be used together with the --email and --password flag.

You can omit the --method=user if you want as it's the default method.

The organization-id flag can be substituted with the INFISICAL_ORGANIZATION_ID environment variable.

kms login --interactive

Description

Forces interactive CLI login where you'll be prompted to enter your email, password, and select your organization in the terminal, instead of opening a browser.

kms login --email=<email> --password=<password> --organization-id=<organization-id> --plain

Description

When used with direct user login or machine identity authentication, outputs only the JWT access token without any additional formatting. This is useful for scripting and CI/CD pipelines where you need to capture the token.

# Example: Capture token in a variable
export INFISICAL_TOKEN=$(kms login --email=<email> --password=<password> --organization-id=<organization-id> --plain --silent)

Use it alongside the silent flag to disable all messages in the console except from the access token.

kms login --jwt=<jwt-token> --machine-identity-id=<machine-identity-id>

Description

The JWT provided by an identity provider for OIDC or plain JWT authentication. This is required if the --method flag is set to oidc-auth or jwt-auth.

The jwt flag can be substituted with the INFISICAL_JWT environment variable.

kms login --domain=<domain-url>

Description

Specifies the Hanzo KMS API URL for non-US Cloud instances. This flag is required when connecting to any instance other than US Cloud (e.g. EU Cloud or self-hosted).

# Example for EU Cloud
kms login --domain="https://eu.kms.hanzo.ai"

# Example for localhost
kms login --domain="http://localhost:8080"

# Example for self-hosted
kms login --domain="https://your-self-hosted-kms.hanzo.ai"

Critical: If you use --domain during login, you must also include it on all subsequent CLI commands (e.g., kms secrets, kms export, etc.). Alternatively, set the INFISICAL_API_URL environment variable to avoid having to use --domain on every command. Refer to the Domain Configuration section for more details.

User Authentication Examples

By default, running kms login without any flags opens your browser for authentication.

# Opens browser for authentication
kms login

The browser will open to the Hanzo KMS login page, and upon successful authentication, the CLI will be automatically authenticated.

Direct login is ideal for CI/CD pipelines and automation scripts where browser-based authentication is not possible.

Using Command-Line Flags

# Basic direct login (defaults to US Cloud)
kms login --email user@example.com --password "your-password" --organization-id "your-organization-id"

# Basic direct login (EU Cloud)
kms login --domain https://eu.kms.hanzo.ai --email user@example.com --password "your-password" --organization-id "your-organization-id"

# Basic direct login (Self-hosted Instance)
kms login --domain https://your-self-hosted-kms.hanzo.ai --email user@example.com --password "your-password" --organization-id "your-organization-id"

# Output only JWT token for scripting
export INFISICAL_TOKEN=$(kms login --email user@example.com --password "your-password" --organization-id "your-organization-id" --plain --silent)

Using Environment Variables (Recommended for CI/CD)

# Set credentials as environment variables
export INFISICAL_EMAIL="user@example.com"
export INFISICAL_PASSWORD="your-password"
export INFISICAL_ORGANIZATION_ID="your-organization-id"

# Login without additional flags
kms login

# Or with plain output for token capture
export INFISICAL_TOKEN=$(kms login --plain --silent)

For non-US Cloud instances: If you're using EU Cloud or a self-hosted instance, you must set INFISICAL_API_URL before login or use --domain on all commands. Refer to the Domain Configuration section for more details.

Interactive login prompts you to enter credentials in the terminal instead of opening a browser.

# Force interactive CLI login
kms login --interactive

You'll be prompted to enter:

• Email address
• Password

After the prompt, you will be shown a list of organizations to choose from.

If you have SSO enabled, we recommend using the default browser login.

Machine Identity Authentication Quick Start

  export INFISICAL_TOKEN=$(kms login --method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --silent --plain) # silent and plain is important to ensure only the token itself is printed, so we can easily set it as an environment variable.

For non-US Cloud instances: If you're using EU Cloud or a self-hosted instance, you must set INFISICAL_API_URL before login or use --domain on all commands. Refer to the Domain Configuration section for more details.

Now that we've set the INFISICAL_TOKEN environment variable, we can use the CLI to interact with Hanzo KMS. The CLI will automatically check for the presence of the INFISICAL_TOKEN environment variable and use it for authentication.

Alternatively, if you would rather use the --token flag to pass the token directly, you can do so by running the following command:

  kms [command] --token=<your-access-token> # The token output from the login command.

  kms secrets --projectId=<your-project-id> --env=dev --recursive

This command will fetch all secrets from the dev environment in your project, including all secrets in subfolders.

The --recursive, and --env flag is optional and will fetch all secrets in subfolders. The default environment is dev if no --env flag is provided.