| name | access-and-policy |
| description | Navigate scai's access model — the workspace policy allowlist and the credential/keychain patterns. Use when a command fails with POLICY_DENIED or AUTH_REQUIRED, when authenticating an environment, or to pick the fastest route to gain access to an environment. |
Access & Policy
Two gates stand between a command and a Sitecore environment: the
workspace policy allowlist and a credential. This skill maps each
failure to the one command that clears it — so you ask the operator for
the right access once, instead of discovering the gates one
round-trip at a time.
Step 0 — always start with scai setup status
It lists every configured environment and, per environment: cmAuth,
deployToken, and credentials (env client / org client /
brand). Read it before guessing — it names which gate is closed.
Gate 1 — the workspace policy allowlist
~/.sitecoreai/policy.json is a deny-by-default allowlist of the
environments scai may operate against.
- File absent → unmanaged mode: the gate is a no-op; every
configured environment is usable.
- File present → managed mode: only enrolled environments work.
| Symptom | Fix |
|---|
POLICY_DENIED — "not in the workspace policy allowlist" | scai policy allow <env> |
POLICY_DENIED — "identity has changed since enrolled" | scai policy trust <env> — only if the org/project/env/host change is real |
| See what's allowed | scai policy show |
| No policy file yet, want one | scai policy init |
| Tune ceiling / CI-writes / mint eligibility | scai policy set <env> |
Enrollment pins the tenant identity (org / project / environment /
host). If the profile's identity later drifts, the gate fails closed —
that is a tamper signal, not a bug.
Gate 2 — credentials
Where credentials live
- Config (
sitecoreai.cli.json) holds only non-secret metadata —
ids, host, the automationClient block's clientId / name.
- Secrets live in the OS keychain, keyed by the literal env
name:
deploy:<env>, cm-client:<env>, org-client:<orgId>.
ref shares config, not secrets
A profile with "ref": "<other-env>" inherits the other env's config
fields — but not its keychain secrets. A ref'd environment still
needs its own credential. (setup status shows cmAuth: missing even
though the inherited automationClient metadata looks present.)
The three credential kinds
| Kind | Keychain slot | Minted by | Lifetime / scope |
|---|
| Deploy token | deploy:<env> | scai setup login (device flow) | ~24h; Deploy API + CM/admin scopes |
| Env CM client | cm-client:<env> | scai setup client create <env> | long-lived; one environment |
| Org client | org-client:<orgId> | scai setup client create --org | long-lived; every env in the org |
The two gotchas that cost the most time
-
Device login needs a TTY. scai setup login is an interactive
browser device flow — it hard-fails (Non-interactive mode: this command requires input) when stdin/stdout is not a TTY. An automated
agent's shell is not a TTY, so an agent cannot trigger device
login — it must ask the human to run it in a real terminal, or use
the non-interactive client-credentials path below.
-
Minting needs a token to bootstrap. scai setup client create
calls the Deploy API, which needs a deploy token for that env — but
a brand-new env has none (chicken-and-egg). Resolve it with either: a
human device login first (which gives the env its own token), or
SITECOREAI_DEPLOY_TOKEN=<token> for the single mint call. Reusing
another env's token is fine within one org, but get the
operator's explicit say-so first — cross-env credential reuse is
otherwise refused.
Non-interactive authentication
When no human / TTY is available, use client credentials — no device
login, no token reuse:
SITECOREAI_CLIENT_ID=<id> SITECOREAI_CLIENT_SECRET=<secret> \
scai <command> -n <env>
or set useClientCredentials: true + clientId on the profile and
supply SITECOREAI_ENV_<ENV>_CLIENT_SECRET.
Decision tree — "how do I gain access to environment X?"
scai setup status — read X's row.- Not in
sitecoreai.cli.json? → scai setup init -n X (or add the
profile), then continue.
POLICY_DENIED? → scai policy allow X (or scai policy trust X on
a legitimate identity change).cmAuth: missing / deployToken: missing?
- Human at a terminal →
scai setup login -n X.
- Want a long-lived credential →
scai setup client create X (env)
or --org (whole org).
- No human, CI-style → client credentials (above).
- Request the minimum ceiling you need —
read for inspection;
only ask for write when a command actually mutates.
When you ask the operator for access
State all four in one message — it collapses the round-trips: the
environment name, the gate that is closed (policy vs
credential), the exact command that clears it, and who must run
it (you, or the human, and why).
Related skills
environment-setup — first-time environment + auth configuration.deploy-ops — Deploy API operations once access is established.troubleshooting — broader error diagnosis.
