Administrator guide

Administrators manage Cloud Certainty StateCraft from Administration in the portal (PortalUrl): connections, grants, roles, settings (including voice and assist), usage, execution records, the audit log, and the licence. Everything is stored in the stack's DynamoDB table in your account, and every change is written to the audit log.

Administration has the pages Connections, Grants, Roles, Settings, Usage, Executions, Audit log and Licence and about.

#Roles

• Everyone who signs in without a role entry is a User, and sees no state machines until a grant applies to them.
• Roles and grants match the user's email or groups. The email must be trusted: asserted by your SAML IdP, verified by your OIDC IdP (email_verified), or marked verified in the Cognito user pool (Identity providers).
• In Administration › Roles, under Grant a role, choose User or Group, enter the email or the group name exactly as your IdP sends it (group names are case-sensitive), choose Administrator or User, and save. A role for a user wins over a role for one of their groups, so you can make a group administrators and keep one member a User. A change applies on the user's next request.
• You can't remove your own Administrator role. Grant it to at least one more person or group.

#The bootstrap admin

BootstrapAdminEmail (a stack parameter) is the bootstrap admin. The first person who signs in with that email is bound to it by their immutable user ID (the Cognito sub) and is always an Administrator, which prevents lock-out. The Roles page shows the entry as set by the stack. The binding is recorded in the audit log (bootstrap.bind). Someone else who later signs in with the same email address but a different user ID is not the bootstrap admin.

#Recovering the bootstrap admin

Reset the binding when the bootstrap admin's user ID changes (the user was recreated, the IdP issues a new subject, or you switched IdentityProvider). Either:

• Use a different person: update the stack and change BootstrapAdminEmail. The first sign-in with the new email takes over the binding.
• Keep the same email: update the stack with BootstrapAdminEmail set to another address you can sign in with, and sign in with it once. Then set it back and sign in with the original email, which takes the binding over again.

If another Administrator can still sign in, they can simply grant the Administrator role to the person by email under Administration › Roles.

#Connections

A connection is one IAM role StateCraft assumes in one AWS account, with the Regions it covers and an access level (Administration › Connections).

#Access levels

The access level of a connection's role is the ceiling for everyone, administrators included. Grants can narrow it per user or group but never widen it.

Whatever the level, the role passes only the execution roles in its stack's PassRoleArns parameter to Step Functions (and only to Step Functions; StateCraft's own roles never), and uses customer managed KMS keys only through Step Functions, limited to the keys in StateMachineKmsKeyArns when you list them (parameter reference).

Use Read for production accounts where people should look but not touch, Operate where on-call engineers need to stop and redrive, and Full only where teams deploy through StateCraft.

#Add a connection

1. Deploy the spoke role in the account (installation guide). How to connect another AWS account at the bottom of the page shows the steps, the template URL and an AWS CLI command. Set TrustedPrincipal to the hub stack's SpokeTrustedPrincipal output (both role ARNs, comma-separated) and choose an ExternalId secret of 16 or more characters.
2. Choose Add connection and enter:
   • Id: a short name used in links, for example production. It can't be changed later.
   • Name and AWS account id.
   • Access level: the same as the spoke stack's AccessLevel.
   • Role ARN: the spoke stack's RoleArn output, arn:aws:iam::<account>:role/statecraft/<RoleName>. It must be in that account and under the /statecraft/ path.
   • External ID: the same secret you gave the spoke stack. It is stored and never shown again; when you edit the connection, leave it empty to keep it.
   • Regions to show.
3. Save connection, then choose Test. The test assumes the role and, for each Region, reports how many state machines it found, or the AWS error.

Each distinct AWS account counts against your plan's account limit, the hub account included (3 on Starter, 10 on Team, 50 on Business, unlimited on Enterprise). When the limit is reached, Add connection is disabled. Deleting a connection makes StateCraft stop using the role, and grants on it stop applying; the role stays in the account until you delete its stack.

#Grants

A grant gives a user or a group permissions on the state machines whose names match some patterns, on a connection (or all) in some Regions (or all) (Administration › Grants). A new grant, or a change, applies on the user's next request.

Screenshot

#How grants combine

• A user's permissions on a state machine are the union of every grant that matches them, through their email or any of their groups, whose connection, Region and patterns match the machine, capped by the connection's access level and the plan.
• Child executions of a Distributed Map belong to the parent state machine: a grant on the parent covers them.
• A user with no matching grant gets "not found" for a state machine: StateCraft doesn't reveal that it exists. A state machine they can see but not use in that way answers "forbidden".
• Administrators have every permission everywhere, still bounded by each connection's access level and the plan.
• State machines whose names contain characters other than letters, digits, _ and - are shown to administrators only.

#How grants are enforced

Grants are enforced twice. StateCraft checks them on every request, and every AWS call runs with temporary credentials (15 minutes) that a per-request session policy limits to the user's grants: Step Functions actions only on the state machines, versions, aliases, executions and Map Runs that match the user's patterns, and only the actions their permissions allow. Even if StateCraft's own check had a bug, AWS would refuse anything outside the grants.

Data without data. IAM can't separate an execution's metadata from its data, so for people without data StateCraft asks Step Functions for metadata only and leaves inputs, outputs and causes out of what it returns. For state machines encrypted with a customer managed key, AWS enforces it as well: the session of a person without data has no permission to decrypt.

If someone's grants would make a session policy larger than AWS allows, StateCraft refuses the request ("too many grants") rather than widening it. Combine grants: use groups, and patterns such as orders-* instead of many single names.

#Examples

#Settings

Administration › Settings:

Screenshot

#Voice and assist

#Voice

People can speak and type commands that build and change workflows and move around the portal (see the user guide). Typed commands are always available. For speech, choose one engine under Settings › Voice:

StateCraft never stores audio or transcripts. Each Transcribe session is counted under Usage, and its signing appears in CloudTrail with the person's email as the source identity. Amazon Transcribe may use content to improve AWS services unless your organisation has an AWS Organizations AI services opt-out policy. For microphone permissions, browser policies and the portal's Content Security Policy, see Voice in the installation guide.

#Assist

Business and above. Assist sends a person's description of a workflow (and, for a change, the current definition) to Claude on Amazon Bedrock in your account and shows the proposal as a diff the person accepts or rejects; nothing is applied or deployed without them. To turn it on:

1. Check the stack's AssistModelId (Claude Opus 5.5 by default) and AssistRegion (the stack's Region by default), and that the model is available to your account there (Assist in the installation guide).
2. Turn on Settings › Assist.

Every request is counted under Usage and recorded in the audit log (assist.workflow, with the first 500 characters of the description). Bedrock bills the tokens to your AWS account.

#Usage

Administration › Usage shows what your teams did through StateCraft over the last 30 days, per day: executions started, stopped and redriven, deploys, TestState runs, bulk job items, voice sessions and assist requests. On Business and above, the same per user, for the 50 users who started the most executions.

Usage is kept for 400 days. It counts actions taken through StateCraft only; executions started by your applications don't appear here (the fleet view's metrics include them).

#Executions

Screenshot

Administration › Executions lists, day by day, who started, stopped, redrove or re-ran which execution through StateCraft, with the connection, Region, state machine and whether it came from a bulk job. Step Functions itself doesn't record who started an execution; these records do, for your plan's history days (30 on Starter, 90 on Team, 365 on Business and 730 on Enterprise). The same person appears on the execution's page.

#Audit log

Administration › Audit log lists events by UTC day, newest first, with the time, the actor, the action, the target and the source IP. Open an event for its details. Filter this page searches the events shown.

Events are kept for your plan's audit days: 30 on Starter, 90 on Team, 365 on Business and 3,650 on Enterprise. Each event is also written to the API's CloudWatch log group, /aws/lambda/<NamePrefix>-api, kept for the stack's LogRetentionDays, so you can forward it to your SIEM.

For a full trail, CloudTrail in each account records every Step Functions, CloudWatch, CloudWatch Logs and KMS call StateCraft makes with sourceIdentity set to the user's email and the role session name sc-<email>. Calls made by a bulk job carry the job owner's email.

#Licence and about

Administration › Licence and about shows your licence, your plan and the installed version.

#Licence

StateCraft reads your AWS Marketplace licence from AWS License Manager in the hub account. The page shows the status, the plan, the entitlements, when the licence is valid until and when it was last checked. Check licence now reads it again (StateCraft otherwise rechecks every 10 minutes).

Without a valid licence every page except this one says a licence is required. Nothing is deleted; subscribing again unlocks StateCraft. Your state machines and executions are not affected: they run in Step Functions whether StateCraft is licensed or not.

#Plan

What your plan includes lists the limits and features of your plan:

Features your plan doesn't include show a plan badge, and StateCraft refuses them. To change plan, see Changing plan.

#Version and updates

The version card shows the installed version and, when update checks are on (UpdateChecks), the latest release, its summary and release notes, whether it is a security release, the oldest supported version, and How to upgrade with the template URL and an AWS CLI command. A banner on the Administration pages announces a newer release once. See Upgrading.