Connecting your servers and pipelines to Uniqkey Secrets Manager with the uniqkey CLI

Uniqkey Secrets Manager stores the secrets your systems use: database passwords, API tokens, connection strings and certificates. Administrators manage them in the Admin Portal. Servers, scripts and CI/CD pipelines read and write them with the uniqkey command line tool (CLI) and an API key. This article explains how to create an API key, install and configure the CLI, use it safely, and solve the problems customers most often run into.

A few terms used throughout:

• An API key is the credential a machine uses. It has two parts: an Access Key ID (starts with UKEY) and a Secret Key (starts with uksm_), which works like the key's password.
• A secret is a value you store in Secrets Manager.
• A path names one secret, like a file: /production/database/password. A prefix is the start of a path, such as /production, and covers everything below it.

Who can use this

• Secrets Manager must be active for your organization. If you do not see Secrets Manager in the Admin Portal menu, contact Uniqkey support.
• API keys are created by an organization administrator. Support accounts and ordinary employees cannot open Secrets Manager.
• An API key belongs to the organization, not to the administrator who created it. It keeps working if that administrator leaves, so when an administrator who handled keys leaves, replace those keys.
• The CLI runs on Windows, macOS and Linux (x64 and ARM). It is a single program with nothing else to install.
• The machine needs outbound HTTPS (port 443) to secrets-manager.production.uniqkey.eu, and to static.uniqkey.eu for installing and updating.

Keep your API keys and secrets safe

• Secrets are encrypted and decrypted on the machine running the CLI. Uniqkey stores only encrypted values and cannot read them. Uniqkey can see a secret's path, when it changed and which API key accessed it, so never put anything secret in a path or in an API key's name.
• Whoever holds an API key can decrypt everything the key is allowed to read. Path restrictions are a permission that Uniqkey checks on every request, not separate encryption: there is one encryption key per organization. Give each key the narrowest scope and paths it needs, and set an expiry.
• Never paste a Secret Key, a credentials file, a .env file or an unredacted log into a ticket, email or chat. Uniqkey support never needs them.
• If an API key may have leaked: disable or delete it immediately on the API keys page, change every secret the key could read at its source (the database, the third-party service), save the new values, and check the audit log for what the key did. Earlier values stay in each secret's version history.

Step 1: Create an API key

1. Log in to the Admin Portal as an administrator.
2. Open Secrets Manager in the left-hand menu. If the portal asks you to confirm on your phone, approve the request in the Uniqkey app within one minute. Secrets Manager requires Trusted Portal to be allowed for your organization.
3. Open API keys in the left-hand menu and click Create API Key.
4. Fill in the fields:
   • Name: what will use the key, for example ci-deploy-production. The name is shown in the audit log for everything the key does.
   • Scope: Read only, Read & write, or Admin (full access). Most pipelines need Read only.
   • Path Restrictions: the prefixes the key may use, for example /production. Leave it empty only if the key really needs every secret.
   • Expiry date (optional): recommended. The earliest date you can pick is tomorrow. The key works until the end of that day in your browser's time zone.
5. Click Create. The Copy your API key now dialog shows the Access Key ID and the Secret Key.
6. Copy both into the place where the machine keeps its credentials. The Secret Key is shown only once. Tick I have stored this API key in a safe place to close the dialog. If the Secret Key is lost, delete the API key and create a new one.

Managing API keys later:

• The API keys page lists every key with its scope, paths, status, expiry (Expires) and Last used. From there a key can be disabled, enabled again or deleted. Both take effect immediately.
• An organization can have at most 50 API keys.
• Reads, changes and rejected requests are recorded in the organization's audit log under the Secrets Manager topic, with the API key's name. Reading a whole prefix with export or run is recorded as one entry that lists the paths.
• To rotate an API key: create a new key, update the machine, check that the old key's Last used stops changing, then delete the old key.

Step 2: Install the CLI

Windows (PowerShell):

irm https://static.uniqkey.eu/cli/install.ps1 | iex

macOS and Linux:

curl -fsSL https://static.uniqkey.eu/cli/install.sh | sh

The installer downloads the right version for the machine and checks it against a published checksum before installing. On Windows the program is signed by Uniqkey, and the installer adds it to your PATH: open a new terminal afterwards. On macOS and Linux it installs to /usr/local/bin, or to ~/.local/bin when that folder is not writable; if the installer tells you to add that folder to your PATH, do so.

Check the installation:

uniqkey version

To install a specific version, which is recommended in CI so builds do not change on their own:

$env:UNIQKEY_VERSION = '1.0.1'; irm https://static.uniqkey.eu/cli/install.ps1 | iex

curl -fsSL https://static.uniqkey.eu/cli/install.sh | UNIQKEY_VERSION=1.0.1 sh

Updating: run the installer again. Removing: delete the uniqkey program and the .uniqkey folder in your user profile, which also removes saved credentials. If your security policy does not allow running a downloaded install script, contact Uniqkey support for a direct download and its checksum.

Step 3: Configure the CLI

On a workstation or server, run:

uniqkey configure

It asks for three things. Press Enter at API url to keep the production address, then paste the Access key id and the Secret key. The Secret Key is shown on screen while you paste it, so do this where nobody can see your screen. The answers are saved in a credentials file:

• Windows: %USERPROFILE%\.uniqkey\credentials
• macOS and Linux: ~/.uniqkey/credentials

The file holds the Secret Key in plain text. Keep it in the user profile of the account that runs the CLI, do not copy it between machines, and never add it to source control or a container image. Keep production API keys only on the machines that need them, not on developer laptops.

The file can hold several profiles. Choose one with --profile (or -p) placed before the command, for example uniqkey -p build-server secret list, or set the UNIQKEY_PROFILE environment variable:

[default]
access_key_id = UKEYXXXXXXXXXXXXXXXX
secret_key = uksm_...

[build-server]
access_key_id = UKEYYYYYYYYYYYYYYYYY
secret_key = uksm_...

In CI/CD pipelines, do not create a credentials file. Set these environment variables from the pipeline's secret store instead; they take precedence over the file:

The CLI uses the production address by default. Only if Uniqkey has given you a different address, set it at the API url prompt of uniqkey configure, or in the UNIQKEY_API_URL environment variable.

Good to know about the credentials file:

• Key names are not case-sensitive, but a name the CLI does not know is an error, so a typo is never silently ignored. Recreate the profile with uniqkey configure if you get one.
• If you create the file in Windows PowerShell 5 with >, the CLI cannot read it. Use uniqkey configure instead.
• uniqkey configure changes only the profile it writes and leaves the rest of the file as it was.

Step 4: Check that it works

uniqkey secret list

If the API key can read secrets, you see their paths. If nothing is listed, the key has no secrets inside its paths yet. If you get an error, see "Troubleshooting".

Using the CLI

Reading a secret:

uniqkey secret get /production/database/password

Writing a secret. Pipe the value in rather than typing it as an argument, so it stays out of your shell history:

# Windows (PowerShell): asks for the value, which stays out of the history
Read-Host 'New value' | uniqkey secret set /production/database/password --overwrite

# macOS and Linux
openssl rand -base64 32 | uniqkey secret set /production/api/session-key --overwrite

Notes:

• One line break at the end of a piped value is removed, so echo and PowerShell pipes work without special options.
• Overwriting keeps the description, tags and type unless you give new ones. If someone changed the secret while the command ran, it stops with exit code 6 instead of overwriting their change. Run it again.
• Options such as --profile and --output json go before the command (uniqkey --output json secret get /p); options of a command, such as --overwrite, go after the path.
• Paths are case-sensitive.

Giving secrets to a program

uniqkey run is the safest way to hand secrets to a program: they go straight into its environment and are never printed or written to disk.

uniqkey run /production/api -- <your command>

• Each secret becomes an environment variable named after the part of the path below the prefix, upper-cased, with other characters turned into _: under /production/api, /production/api/stripe-key becomes STRIPE_KEY.
• If two secrets would get the same name, or a name would be one that changes how programs start (such as PATH), the command stops before running anything. Rename the secret.
• The variables UNIQKEY_ACCESS_KEY_ID and UNIQKEY_SECRET_KEY are not passed on to the program.
• run exits with the exit code of the program it ran.

Loading secrets into a shell or .env file

uniqkey export prints the secrets as statements for a shell. The default format is PowerShell on Windows and POSIX shell on macOS and Linux.

# Windows (PowerShell)
uniqkey export /production/api | Out-String | iex

# macOS and Linux (bash, zsh, sh); in Git Bash on Windows add --format posix
eval "$(uniqkey export /production/api)"

# Docker Compose .env file (macOS and Linux)
(umask 077; uniqkey export /production/api --format dotenv > .env)

• export prints secrets in plain text. Use it only where the output is consumed immediately, and prefer run.
• A .env file holds every secret under the prefix in plain text. Keep it out of source control (add it to .gitignore), keep it readable only by you, and delete it when you are done. On Windows, create it from cmd (cmd /c "uniqkey export /production/api --format dotenv > .env"), because Windows PowerShell 5 writes > output in a format Docker Compose cannot read.
• The .env format is for tools that read .env files, such as Docker Compose. It is not a shell script: never load it with source or . .env, because a value containing quotes, $ or backticks can then run commands.
• In PowerShell, accented characters, emoji and line breaks arrive unchanged, also on locked-down machines. An empty secret removes the variable instead of setting it to empty.
• If the prefix matches no secrets, the CLI prints a warning and outputs nothing; in PowerShell the iex step then shows an error about an empty string. Check the prefix and the API key's paths.

Using it in CI/CD

1. Store the Access Key ID and Secret Key as secret variables in the pipeline, and map them to UNIQKEY_ACCESS_KEY_ID and UNIQKEY_SECRET_KEY.
2. Install a pinned version of the CLI with the commands in Step 2.
3. Run your step through uniqkey run /production/api -- <your deploy command>.

The pipeline masks the two API key variables in its logs, but it does not know about values the CLI fetches at runtime. Prefer run, which keeps them out of the log. If you print or export values, mask them explicitly in your CI system, and do not use set -x, env or debug logging around those steps. Do not run uniqkey configure in a pipeline.

Kubernetes

For Kubernetes, the CLI includes a small proxy, uniqkey serve, that the External Secrets Operator reads through. It decrypts inside your cluster, so applications receive an ordinary Kubernetes secret. Use a Read only API key limited to the prefixes the cluster needs, run the proxy with a TLS certificate, and use a NetworkPolicy so that only the External Secrets Operator can reach it. The resulting Kubernetes secrets are stored in your cluster in plain text unless you enable encryption at rest. Contact Uniqkey support for the deployment manifests.

Exit codes

Every command exits with a code a script can check. Error messages go to the error output and start with uniqkey:; values go to the normal output. uniqkey run exits with the code of the program it ran.

Limits

Every CLI command first unlocks the organization's encryption, which counts toward the per-IP limit. All machines that reach Uniqkey through the same public IP address (for example behind one NAT or proxy) share it, so a pipeline that runs uniqkey secret get many times a minute can be rate limited even though each API key is far below its own limit. Read a whole prefix with one run or export instead of many secret get calls.

Troubleshooting

When contacting support, include your organization name, the output of uniqkey version, the operating system, the exact command with any secret value removed, the full error message, the exit code (echo $? in bash, $LASTEXITCODE in PowerShell), the API key's name (never the Secret Key) and the time it happened.