Plugipay
ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Plugipay Docs
⌘K

CLI authentication

The CLI authenticates with the same HMAC API keys you use for server-to-server API calls — not with your browser session. This page covers minting a key, storing it, and switching between profiles.

If you're new to API keys, the dashboard flow is in Portal → API keys.

Quick path

plugipay auth login

The CLI prompts you for your access key ID and secret. They're saved to ~/.plugipay/config.json for next time.

plugipay auth whoami

Confirms you're logged in and shows which workspace and key.

How auth works

The CLI uses HMAC API keys, not OIDC sessions. Two pieces:

  • Access key ID — the public identifier (e.g., pk_test_AKIAxxxxxxxxxx). Safe to log.
  • Secret access key — the secret (e.g., sk_test_xxxxxxxxxx). Never log, never commit.

When you run a CLI command, the CLI:

  1. Reads the access key ID and secret from ~/.plugipay/config.json (or env, see below).
  2. Computes an HMAC-SHA256 signature of the request (timestamp + method + path + body hash).
  3. Adds the three signing headers (X-Plugipay-Key-Id, X-Plugipay-Timestamp, X-Plugipay-Signature) to every outgoing request.

You never see this. It's automatic on every command.

Get an API key

  1. Open the Plugipay dashboard.
  2. Go to Settings → API keys.
  3. Click Create API key.
  4. Pick:
    • A name (e.g., "Laptop — CLI").
    • An environment (test or live).
    • A role (full_access, read_only, etc.).
  5. Click Create. The secret appears once — copy it now.

You'll have a pair like:

Access key ID:      pk_test_AKIAxxxxxxxxxx
Secret access key:  sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxx

The secret appears only once. If you close the dialog without copying it, you need to create a new key (the old one can't be retrieved). The CLI then prompts for the new pair.

Login

Run:

plugipay auth login

You'll see two prompts:

Access key ID:       (your typing is hidden)
Secret access key:   (your typing is hidden)

Both inputs are hidden (no echo) so the secret doesn't end up in your terminal scrollback. Paste the values from the dashboard.

After login:

Logged in. Credentials stored at ~/.plugipay/config.json

You're set. The CLI will use these credentials for every subsequent command.

Non-interactive login

For CI environments, you can pass the credentials inline:

plugipay auth login --token "pk_test_AKIAxxxxx:sk_test_xxxxx"

Or with separate flags:

plugipay auth login \
  --access-key-id pk_test_AKIAxxxxx \
  --secret-access-key sk_test_xxxxx

For one-off CI runs, you can skip login entirely and pass the key inline on each command:

plugipay --api-key "pk_test_AKIAxxxxx:sk_test_xxxxx" customers list

Or via env vars (see Configuration):

export PLUGIPAY_API_KEY="pk_test_AKIAxxxxx:sk_test_xxxxx"
plugipay customers list

Verify

After login, confirm everything's wired:

plugipay auth whoami

Output:

accountId:  acc_01Hxxxxxxxxx
email:      alice@example.com
mode:       test
profile:    default

If you see this, you're authenticated and ready to use any command.

Logout

plugipay auth logout

This deletes ~/.plugipay/config.json. The CLI will prompt for credentials again on the next command.

You don't need to logout for security — revoking the API key in the dashboard takes effect server-side and the CLI will start failing with 401 Unauthorized within seconds.

Profiles

You can have multiple credential sets at once (e.g., separate test and live keys, separate workspaces):

plugipay auth login --profile work
# Prompts and saves to ~/.plugipay/config-work.json

plugipay auth login --profile personal
# Saves to ~/.plugipay/config-personal.json

To use a profile:

plugipay --profile work customers list
plugipay --profile personal customers list

Or set the default profile via env:

export PLUGIPAY_PROFILE=work
plugipay customers list  # uses work

Profile precedence (highest to lowest):

  1. --profile <name> flag
  2. PLUGIPAY_PROFILE env variable
  3. default (loads ~/.plugipay/config.json)

See Configuration for the full file format.

Rotating keys

To rotate a compromised or stale key:

  1. Create a new key first. Don't revoke the old one until the new one is verified working.
  2. Update the CLI: plugipay auth login and paste the new credentials.
  3. Test: plugipay auth whoami — should succeed.
  4. Revoke the old key: in the dashboard, Settings → API keys → → Revoke.

The order matters — revoke before testing the new key, and you have a window where neither works.

Multi-workspace

A single Huudis identity can own multiple Plugipay workspaces, but each API key is scoped to one workspace. To work across workspaces from the CLI:

  • Mint one key per workspace.
  • Store them as separate profiles (plugipay auth login --profile workspace-a).
  • Switch with --profile.

If you need to switch the dashboard view to match what you're CLI-ing against, the workspace switcher is at the top-left of the dashboard.

Common errors

401 invalid_signature

The HMAC signature didn't validate. Causes:

  • Clock skew — your system clock is more than 5 minutes off server time. Run ntpdate -q pool.ntp.org or check System Settings → Date & Time and enable automatic time.
  • Wrong secret — you may have copied it from the wrong key or only partially. Re-login with the full secret.

401 invalid_key

The access key ID doesn't exist or has been revoked. Mint a new one in the dashboard.

403 forbidden

The key exists but doesn't have permission for the operation. Either your key's role is too restrictive, or you're trying to access another workspace's data. Check the key's role in the dashboard.

404 not_found on auth whoami

The CLI is hitting the wrong base URL. Check --api flag and PLUGIPAY_BASE_URL env var. Defaults to https://api.plugipay.com.

Next

Plugipay — Payments that don't tax your success