access-and-policy

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

1. 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.

2. 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?"

1. scai setup status — read X's row.
2. Not in sitecoreai.cli.json? → scai setup init -n X (or add the profile), then continue.
3. POLICY_DENIED? → scai policy allow X (or scai policy trust X on a legitimate identity change).
4. 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).
5. 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.