Multi-org Workflow

One email can belong to multiple ArmorIQ organizations, but every API key is scoped to exactly one. The CLI gives you three commands to navigate that split — armoriq orgs, armoriq switch-org, and armoriq login --org — so you can move between orgs without re-running the browser device-code flow.

Why orgs matter

Every resource in ArmorIQ lives inside an organization:

• API keys — scoped to one org. A key issued for "ACME Corp" can't talk to MCPs registered in "Demo Org."
• MCP servers — registered per-org.
• Policies — defined per-org.
• Audit logs — filtered per-org.

So "which org am I in right now?" determines what your agent can do. The CLI stores the active org on disk in ~/.armoriq/credentials.json.

List the orgs you belong to

armoriq orgs

  NAME         ORG_ID                                ROLE        MEMBERS
  ----------------------------------------------------------------------
✓ ACME Corp    144e79f7-7873-41f1-aed8-0ebb5b108200  org_admin   11
  Demo Org     d8ec1877-d828-4f78-9f03-f374a01e55ae  org_admin   10
  Side Project 50901712-32e6-4d45-8f2a-83a56b46653c  iam_admin    2
  Stripe Demo  fa2be516-9ff3-4328-952f-10a3420cd249  org_admin    7

The ✓ marks the active org — the one your current API key is scoped to.

Switch to a different org

armoriq switch-org "Stripe Demo"
# or by UUID
armoriq switch-org fa2be516-9ff3-4328-952f-10a3420cd249

The CLI:

1. Calls the backend to mint a fresh API key scoped to the target org.
2. Updates ~/.armoriq/credentials.json with the new key + new orgId.
3. Clears ~/.armoriq/state.json — the agent you registered in the previous org is no longer active.

✓ Switched to Stripe Demo (org_id=fa2be516-...)
✓ New API key saved.
  Previous agent registration cleared. Re-run `armoriq register` in this org.

After switching, re-run armoriq register --config armoriq.yaml if you want your agent registered in the new org too. (Agent rows are org-scoped; the previous registration still exists in the old org — just isn't local state anymore.)

Name the new key

switch-org mints a CLI key labeled cli-YYYY-MM-DD by default. Override with --key-name:

armoriq switch-org "Stripe Demo" --key-name "alice-macbook"

The label shows up in the API Keys dashboard so you can tell which physical machine holds which key.

Pre-select an org at login

Skip the switch dance on a fresh machine by passing --org to armoriq login:

armoriq login --org "Stripe Demo"

The browser's approval page pre-selects "Stripe Demo" in the org dropdown — one click to confirm instead of remembering to switch afterward.

Works with UUIDs too:

armoriq login --org fa2be516-9ff3-4328-952f-10a3420cd249

API key lifecycle

Good rotation hygiene

Every few weeks, or any time you lose a laptop:

1. armoriq orgs → note the active org.
2. Open the API Keys dashboard for that org.
3. Delete any keys with a cli-... prefix and a label you don't recognize.
4. armoriq login again if you deleted the one on your current machine.

Common workflows

Working across two orgs in one day

armoriq switch-org "ACME Corp"
armoriq register --config acme-agent.yaml
# ... test, iterate ...

armoriq switch-org "Stripe Demo"
armoriq register --config stripe-agent.yaml
# ... different config, different MCPs, same user ...

Each switch-org is a one-liner — no browser.

Scripting registrations across orgs

#!/usr/bin/env bash
# deploy-all-orgs.sh
set -e

for org in "ACME Corp" "Stripe Demo"; do
  armoriq switch-org "$org"
  armoriq register --config "configs/$(echo $org | tr ' ' '-').yaml"
done

In CI, switch-org isn't the right tool — use a per-org API key stored as a secret instead:

# .github/workflows/deploy.yml
jobs:
  deploy-acme:
    env:
      ARMORIQ_API_KEY: ${{ secrets.ARMORIQ_API_KEY_ACME }}
    steps:
      - run: armoriq register --config acme-agent.yaml

  deploy-stripe:
    env:
      ARMORIQ_API_KEY: ${{ secrets.ARMORIQ_API_KEY_STRIPE }}
    steps:
      - run: armoriq register --config stripe-agent.yaml

Each key is pinned to its org — no switch command needed.

Invitations and new orgs

To join an org you don't belong to yet:

1. An admin of that org creates an invitation pointing at your email.
2. You accept via the dashboard.
3. Your next armoriq orgs will include the new org.
4. Switch to it with armoriq switch-org "New Org Name".

Troubleshooting

Next steps