Fjall Docs — deploy AWS infrastructure into your own account

Prerequisites

Complete one of:

Connect AWS Account (account-mode users)
Deploy Organisation (organisation-mode users)

Overview

Authentication and the choice of which AWS account a deploy lands in are two separate concerns. Neither is driven by a manual profile step, and neither is stored in fjall-config.json.

Concept	What it does	Where it comes from
Authentication profile	Authenticates the CLI against an AWS account (OIDC or SSO)	Derived in memory from your organisation config
Deployment target	Selects the account and region a deploy lands in	Derived from your accounts, selected with `fjall target set`

You supply exactly one credential: the Fjall one. fjall login writes ~/.fjall/auth.json (or $FJALL_CONFIG_DIR/auth.json). Everything AWS is derived from there.

There is no fjall profile command, and Fjall never reads or writes ~/.aws/config or ~/.aws/credentials. aws sso login is not part of the flow.

Authentication modes

Both modes derive from the same organisation config, which Fjall fetches from the API (GET /api/organisation-config, cached for five minutes). Account mode. You connected a single AWS account with fjall connect. The account carries its own OIDC role, so Fjall mints a token from the Fjall API and calls STS AssumeRoleWithWebIdentity against that role. Organisation mode. You scaffolded a multi-account organisation with fjall create organisation and deployed it with fjall org deploy, which resolves the IAM Identity Center instance you enabled in the console. Member accounts that have no OIDC role of their own authenticate through SSO. OIDC applies whenever an account carries its own oidcRoleArn, including the pre-org deploy state right after Quick Create. SSO applies to organisation members that lack one.

How profiles are derived

deriveProfiles(orgConfig) is a pure, in-memory derivation. Three arms cover every account.

Account	Profile name	Auth
Root (Organizations management account)	`<rootname>`	OIDC, single profile
Non-root carrying its own `oidcRoleArn`	`<account>-<regionabbrev>`	OIDC, one per region
Non-root organisation member (no OIDC role)	`<rootname>-<account>-<regionabbrev>`	SSO, one per region

The region abbreviation collapses an AWS region to a short token: us-east-1 becomes use1, us-east-2 becomes use2, eu-west-1 becomes euw1. SSO profiles use the AdministratorAccess role and the sso-<rootname> session resolved from your organisation config.

Environment credentials override derivation

Authentication reads the process environment before any derivation runs. When both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set, Fjall uses those credentials directly under the profile name environment-credentials and returns. AWS_SESSION_TOKEN is used when present.

Environment credentials come first and end the resolution there. Nothing above is consulted: no organisation config lookup, no derived profile name, no OIDC or SSO flow. A stale AWS_ACCESS_KEY_ID left exported in your shell silently outranks every derived profile, so unset both variables to go back to derivation.Both variables must be set for the short circuit to fire. With only one of them set, Fjall falls through to normal derivation. For the CI framing, see CI/CD deploys.

The region is still resolved separately, from -r, --region first, then AWS_REGION, then AWS_DEFAULT_REGION, then us-east-2. Fjall validates the supplied keys with STS GetCallerIdentity before returning them, so expired keys fail at authentication rather than part-way through a deploy.

Inspecting derived profiles

Profiles are computed at run time and never written to disk, so aws configure list-profiles returns nothing about Fjall. Inspect the derived accounts and regions through the CLI instead:

# Every deployment target derived from your organisation config
fjall target list

# The active target's account, account ID and region
fjall target get

The only Fjall-related file under ~/.aws is the SSO token cache at ~/.aws/sso/cache, which holds a short-lived token rather than any profile definition.

SSO re-authentication

When an organisation-mode SSO token has expired, Fjall runs the SSO device-authorisation flow at deploy time and opens your browser. A cached, valid token prints nothing at all. In --non-interactive runs the URL is printed for you to open:

SSO authentication required. Open this URL in your browser:
  https://d-**********.awsapps.com/start/#/device?user_code=***-***

AWS Identity Center sign-in page, opened in your browser.

Selecting a deployment target

A target is an account and region pair, named <accountname>-<regionabbrev>, for example production-use1 or development-euw1. Targets are derived by crossing every non-organisation-tier account with your organisation’s configured regions (primary, secondary and disaster recovery). Root accounts are excluded.

# List all derived targets (the active one is marked with ▸)
fjall target list

# Show the active target
fjall target get

# Set the active deployment target
fjall target set production-use1

fjall target list prints one row per target with its environment, account and region, marks the active target with ▸, and closes with an Active: <name> line. A row may carry a readiness annotation too: ✓ ready, or ! not ready — <reason> when the target cannot be deployed to yet. Rows whose readiness was not probed carry no annotation.

Where the active target is stored

fjall target set writes activeTarget to .fjall/local.json, a git-ignored file beside fjall-config.json. The active target is per developer and per checkout, so a colleague’s choice or a CI pipeline never inherits yours.

An activeTarget inside the committed fjall-config.json is legacy. Fjall reads it only to print a deprecation warning, then behaves as if no target were set. Delete it from the committed file and run fjall target set <name> instead.

Options for `fjall target set`

Option	Effect
`-y, --yes`	Add the target’s region to your organisation’s regions without prompting
`--create-config`	Create a `fjall-config.json` here even though no Fjall project was found

fjall target set refuses in four cases:

You are not signed in to Fjall.
You are outside any Fjall project and did not pass --create-config.
The project’s organisation binding names a different organisation from your current credential.
The target’s region is not one of your organisation’s configured regions.

Case 4 is not cosmetic. Interactively, Fjall offers to add that region as a secondary region (or as the primary region when none is set yet) and writes it back to your organisation config, where it becomes available to every account and is included in organisation deploys. Non-interactively the command fails and points you at -y, --yes.

How the deploy account is resolved

At deploy time Fjall walks one precedence chain and fails closed at the end.

--target <name> on the command. An unknown name is a hard error listing the valid targets, never a silent fallback.
activeTarget from .fjall/local.json.
Auto-select when exactly one target exists, or the root profile when no targets exist. The tier deploys count differently: fjall account deploy auto-selects when the organisation has exactly one member account, so a single account spanning two regions still resolves without a prompt.
Refuse, listing the candidate targets and pointing at fjall target set.

-r, --region overrides the region within the resolved target’s account. The positional argument to fjall deploy is the application name, not a target:

fjall deploy api --target production-use1

Tier deploys are noun-verb: fjall org deploy, fjall platform deploy, fjall account deploy. Passing a tier word to fjall deploy fails before authentication with a teaching error.

The environment flag is not a target selector

fjall deploy accepts -e, --environment <env>, but it selects no account, no region and no target.

fjall deploy api --environment production

Its one live effect is choosing the .env.<stage> Docker build-arg tier during the image build. Treat it as a CI build-arg label. The environment that actually drives synthesis (and therefore every removal policy) comes from the target account’s own record, not from a flag. Fjall resolves it from your organisation config, uses root for the organisation tier and the account’s recorded stage otherwise, then passes it to CDK as both ENVIRONMENT= and -c environment=. A deploy fails closed if that value cannot be resolved. A second, unrelated -e, --environment exists on fjall account deploy. It is constrained to production, staging, development, platform and compliance, and it stamps the workload stage recorded for a standalone account registration. Fjall rejects it for an account that already belongs to an organisation. The same vocabulary appears on fjall connect --environment.

What fjall-config.json contains

fjall-config.json is the committed project marker. Its strict write schema declares exactly four optional keys.

Key	Purpose
`organisation`	The Fjall organisation this project deploys into (`{ id, name? }`)
`domains`	Declared domains (`{ name, type, parentDomain?, account?, region? }`)
`capacityIdentity`	Frozen capacity-slot identity pins, keyed application then target then slot
`activeTarget`	Legacy and ignored for resolution. Delete it.

{
  "organisation": { "id": "org_2f8c1a4e", "name": "Acme" },
  "domains": [{ "name": "example.com", "type": "apex" }],
  "capacityIdentity": {
    "api": {
      "production-use1": {
        "primary": { "legacyAnchor": "ApiClusterPrimary" }
      }
    }
  }
}

Never delete a capacityIdentity pin. Each pin is load-bearing deployed state, and removing one renames (replaces) every stateful resource in its slot on the next deploy.

There is no deploy mapping, no environments block, no stage field and no account or region mapping of any kind. Accounts, regions, OIDC role ARNs and SSO sessions live in your organisation config, which Fjall fetches from the API and injects into the deploy.

Next Steps

Deploy Platform

Deploy your platform account in organisation mode.

Deploy Application

Deploy an application to your selected target.

Deploy Organisation

Set up a multi-account organisation.

Connect AWS Account

Connect a single account in account mode.

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

AWS Profiles and Targets

Overview

Authentication modes

How profiles are derived

Environment credentials override derivation

Inspecting derived profiles

SSO re-authentication

Selecting a deployment target

Where the active target is stored

Options for `fjall target set`

How the deploy account is resolved

The environment flag is not a target selector

What fjall-config.json contains

Next Steps

Deploy Platform

Deploy Application

Deploy Organisation

Connect AWS Account

​Overview

​Authentication modes

​How profiles are derived

​Environment credentials override derivation

​Inspecting derived profiles

​SSO re-authentication

​Selecting a deployment target

​Where the active target is stored

​Options for fjall target set

​How the deploy account is resolved

​The environment flag is not a target selector

​What fjall-config.json contains

​Next Steps

Deploy Platform

Deploy Application

Deploy Organisation

Connect AWS Account

Overview

Authentication modes

How profiles are derived

Environment credentials override derivation

Inspecting derived profiles

SSO re-authentication

Selecting a deployment target

Where the active target is stored

Options for `fjall target set`

How the deploy account is resolved

The environment flag is not a target selector

What fjall-config.json contains

Next Steps