Authentication

All communication between your agent and ArmorIQ is authenticated by an API key. The CLI logs you in once and stores that key locally; the SDK reads it automatically. In production, you pass the key through environment variables instead.

Logging in

Run armoriq login to authenticate your developer workstation. It opens a browser tab for you to sign in, mints a new API key scoped to your account + organization, and saves it to ~/.armoriq/credentials.json.

$ armoriq login

  ArmorIQ Login

  Opening browser...

  If the browser didn't open, visit:
    https://platform.armoriq.ai/auth/device?code=XXXX-XXXX

  Confirm this code in your browser: XXXX-XXXX

  Waiting for authorization... ✔

  ✔ Logged in as alice@acme.com (org: 144e79f7-7873-...)
  ✔ API key saved to /Users/alice/.armoriq/credentials.json

armoriq whoami shows your current identity without hitting the network:

$ armoriq whoami

  ArmorIQ Credentials

  Email:    alice@acme.com
  API Key:  ak_live_xxxxxxxx...
  User ID:  8c0b55f8-b052-4041-9d15-02835bd919ad
  Org ID:   144e79f7-7873-41f1-aed8-0ebb5b108200
  Saved at: 2026-04-22T08:48:08+00:00
  File:     /Users/alice/.armoriq/credentials.json

The credentials file

~/.armoriq/credentials.json is created on first login with 0600 permissions (owner read/write only). Shape:

{
  "apiKey": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "email": "alice@acme.com",
  "userId": "8c0b55f8-b052-4041-9d15-02835bd919ad",
  "orgId": "144e79f7-7873-41f1-aed8-0ebb5b108200",
  "savedAt": "2026-04-22T08:48:08+00:00"
}

Both the Python and TypeScript SDKs read this file — a single armoriq login works for both runtimes on the same machine.

Logging out

armoriq logout deletes the local credentials file. It does not revoke the server-side API key — anyone who still holds the key value can keep using it.

$ armoriq logout
  ✔ Credentials removed from /Users/alice/.armoriq/credentials.json

To fully revoke a key, open the API Keys dashboard and rotate or delete it.

Key resolution order

Both SDKs resolve the API key in this priority order:

The first source that yields a non-empty string wins. A missing key raises ConfigurationException.

Using keys in production

In CI, containers, or cloud deployments, the credentials file doesn't exist. Set the env var instead:

export ARMORIQ_API_KEY=ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
python my_agent.py

ARG ARMORIQ_API_KEY
ENV ARMORIQ_API_KEY=${ARMORIQ_API_KEY}
CMD ["python", "my_agent.py"]

apiVersion: v1
kind: Secret
metadata:
  name: armoriq-key
stringData:
  api-key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: agent
          env:
            - name: ARMORIQ_API_KEY
              valueFrom:
                secretKeyRef:
                  name: armoriq-key
                  key: api-key

jobs:
  run-agent:
    runs-on: ubuntu-latest
    env:
      ARMORIQ_API_KEY: ${{ secrets.ARMORIQ_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: pip install armoriq-sdk
      - run: python my_agent.py

Rotating a key

1. Open the API Keys dashboard.
2. Click Create Key → name it (e.g. prod-2026-Q2) → copy the value.
3. Update your production secret store (Kubernetes, GitHub secrets, Vault, etc.).
4. Roll your pods / restart your services.
5. Once traffic has moved, delete the old key.

No code changes required — the SDK picks up the new value on the next process start.

API key formats

Every ArmorIQ key starts with one of these prefixes:

The SDK refuses to initialize with a malformed or unknown prefix — you'll see Invalid API key format in the ConfigurationException message.

Troubleshooting

Next steps