Issuing auth keys

Auth keys (tskey-auth-<random>) are the credential the ztna agent uses to enrol new devices into your tailnet. This guide covers the decisions you need to make before issuing one — reusable vs ephemeral, expiry, tags — plus rotation and revocation patterns.

When to issue an auth key

You need an auth key when enrolling a device via the ztna installer with no browser. Typical cases:

• MDM rollout (Intune, Jamf, Airwatch) pushing the installer to 100+ laptops
• Ansible / Terraform / cloud-init provisioning servers
• CI/CD runners (GitHub Actions, GitLab CI) needing ephemeral tailnet access
• Docker containers with ZTNA_AUTH_KEY as a secret

If a user is interactively setting up one device, they don't need an auth key — they can just run ztna login and authenticate through the browser.

Key design decisions

Reusable vs one-shot

Ephemeral vs persistent

Expiry

How long the key is valid for enrolling new devices (not how long enrolled devices stay authenticated). Range: 5 minutes — 30 days.

• 1 hour — right default for fleet rollouts
• 24 hours — convenient for async MDM rollouts
• 7-30 days — for CI runner pool that constantly churns

Tags

Tags applied to each enrolled device. Used in ACL rules — e.g. a rule "tag:laptop can SSH to tag:prod" applies to any machine with tag:laptop.

Prefix with tag:. Multiple tags via comma-separated list. Tags can be added later via ztna set --tags, but setting them at enrolment time means they're correct from first heartbeat.

Issuing the key

Via dashboard

1. Go to Settings → API Keys → Auth Keys
2. Click Create auth key
3. Fill in: reusable, ephemeral, expiry, tags, description
4. Copy the returned key (tskey-auth-...) — you cannot retrieve it again

Via CLI (admin only)

$ ztna auth-key create \
    --reusable \
    --expiry 1h \
    --tags tag:laptop,tag:eng \
    --description "Q2 laptop fleet rollout"

✓ Auth key created: tskey-auth-abc123def456
  Reusable:     yes
  Ephemeral:    no
  Expires:      in 1 hour
  Tags:         tag:laptop, tag:eng
  Description:  Q2 laptop fleet rollout

COPY THIS KEY NOW — you cannot retrieve it later.

Via API

$ curl https://login.quickztna.com/api/key-management \
    -H "Authorization: Bearer $QZ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "create_auth_key",
      "org_id": "org_9fX2kR",
      "reusable": true,
      "expires_in": 3600,
      "tags": ["tag:laptop", "tag:eng"],
      "description": "Q2 laptop fleet rollout"
    }'

resource "quickztna_auth_key" "q2_rollout" {
  org_id      = "org_9fX2kR"
  reusable    = true
  expires_in  = 3600
  tags        = ["tag:laptop", "tag:eng"]
  description = "Q2 laptop fleet rollout"
}

output "key" {
  value     = quickztna_auth_key.q2_rollout.key
  sensitive = true
}

Rolling the key out

Set ZTNA_AUTH_KEY in the environment and run the installer. The agent auto-registers + connects.

- name: Enrol device in QuickZTNA
  shell: curl -fsSL https://login.quickztna.com/install.sh | ZTNA_AUTH_KEY={{ ztna_key }} sh
  environment:
    ZTNA_AUTH_KEY: "{{ ztna_key }}"
  vars:
    ztna_key: "{{ lookup('env', 'ZTNA_KEY') }}"

#cloud-config
runcmd:
  - curl -fsSL https://login.quickztna.com/install.sh | ZTNA_AUTH_KEY=tskey-auth-xxx sh

- name: Install QuickZTNA
  run: curl -fsSL https://login.quickztna.com/install.sh | sh
  env:
    ZTNA_AUTH_KEY: ${{ secrets.ZTNA_EPHEMERAL_KEY }}

FROM ubuntu:24.04
ARG ZTNA_AUTH_KEY
RUN curl -fsSL https://login.quickztna.com/install.sh | ZTNA_AUTH_KEY=$ZTNA_AUTH_KEY sh
ENTRYPOINT ["ztna", "up", "--userspace"]

Rotation

Auth keys don't rotate themselves — because they're only used at enrolment. After enrolment, each machine uses a permanent node_key that's separately revocable.

Recommended hygiene:

• Revoke after use. Once your fleet rollout completes, revoke the key from Settings → API Keys → Auth Keys, or ztna auth-keys revoke tskey-auth-abc...
• Short expiry. 1-hour expiry is fine for most rollouts. Set the expiry even if you plan to revoke — it's defence in depth.
• Don't commit keys. Treat auth keys like passwords. Use your secret manager.

Revoking

Revoke an auth key to prevent future enrolments. Machines already enrolled with the key are unaffected (they have node_keys of their own).

$ ztna auth-keys list
PREFIX             REUSABLE  USES  EXPIRES
tskey-auth-abc12…  yes       87    in 45 min

$ ztna auth-keys revoke tskey-auth-abc123
✓ Revoked — future enrolments with this key will fail

$ curl https://login.quickztna.com/api/key-management \
    -H "Authorization: Bearer $QZ_API_KEY" \
    -d '{
      "action": "revoke_auth_key",
      "org_id": "org_9fX2kR",
      "key_id": "ak_9fX2kR"
    }'

See also

• Installing the agent — how the installer uses this key
• Approving + managing devices — what comes after enrolment
• API: create_auth_key — full request/response reference