External Operator Quickstart

This flow is the supported pattern for external operators (for example AvatarOps) configuring a DriftGate workspace.

Prerequisites

• DriftGate workspace ID
• Service account with required workspace role/scope
• Token secret with dgk_* prefix
• DriftGate CLI @driftgate/cli@1.0.1 or newer

1) Configure API Key Auth

export DRIFTGATE_API_KEY=<dgk_secret>
export DRIFTGATE_API_BASE=https://api.driftgate.ai

Do not use dg_sa_*; it is an identifier, not a secret.

2) Validate Admin/Config Access

driftgate policies list --workspace <workspaceId> --api-base "$DRIFTGATE_API_BASE"
driftgate routes list --workspace <workspaceId> --api-base "$DRIFTGATE_API_BASE"

If either fails with unauthorized, verify token scope, workspace binding, and service-account status.

3) Validate Runtime Separation (Expected Failure)

driftgate execute --agent avatarops-access-check --input '{"ping":"pong"}' --api-base "$DRIFTGATE_API_BASE"

Expected result: runtime auth rejection (missing session token / AUTH_INVALID) because runtime requires session auth.

4) Revoke and Confirm Containment

1. Revoke token in Access Control.
2. Re-run policies list or routes list.
3. Confirm request is denied.

Troubleshooting

• invalid api key: dg_sa_* -> you supplied service-account ID instead of token secret.
• missing session token on runtime commands -> expected for API-key auth.
• workspace scope denied -> token scope/role does not include target workspace.

Canonical references:

• Auth + Token Contract
• Operator Auth + Token Runbook