> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Account access

> Account ownership, initial administrator access, and user or group role assignments.

An account owns resources and account IAM identities. Roles, service accounts,
account policies, and STS sessions belong to one account even though IAM has a
global endpoint. Selecting another region leaves that ownership unchanged.

## Creating an account

Workspace creates accounts at `POST /v1/accounts`. The response includes the
new account and its `bootstrap_role_id` and `bootstrap_role_crn`.

Creation also creates an `AccountAdministrator` role in the account. It has
the system account `Administrator` policy and trusts only the creator's
immutable identity. A human creator receives a role assignment automatically.
A machine creator still needs `iam:AssumeRole` in its source account policy
before it can assume the bootstrap role.

The bootstrap role is an ordinary custom role: review its trust, replace its
broad permissions with suitable roles, and delete it when it is no longer
needed. It does not give the account authority over the organization.

## Assigning people to account roles

In the console, open **Organization** → **Accounts**, select the account,
then open **Settings**. The **Account access** card lets you **Assign role**
to a user or group. A group assignment applies to its user members.

An assignment and the role's trust policy are separate requirements:

1. The assignment authorizes the human to request `iam:AssumeRole` for that role.
2. The role's trust policy must accept that user's Workspace principal CRN.
3. After assumption, account requests use the role's permissions.

Assigning a role never silently changes its trust policy. Open the role's
**Trust Policy** editor to allow the intended users. A group is not an
assuming principal: use the users' principal CRNs, or an organization-scoped
user pattern together with controlled role assignments.

<Warning>
  Broad trust does not replace an assignment. An assignment does not replace
  trust. Both must permit the exchange.
</Warning>

The Workspace API exposes these operations:

| Operation                                       | Endpoint                                                            |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| List an account's assignments                   | `GET /v1/accounts/{account_id}/role-assignments`                    |
| Assign a user or group                          | `POST /v1/accounts/{account_id}/role-assignments`                   |
| Remove an assignment                            | `DELETE /v1/accounts/{account_id}/role-assignments/{assignment_id}` |
| List the current user's effective account roles | `GET /v1/account-roles`                                             |

An assignment contains `principal_type` (`user` or `group`), `principal_id`,
and `role_id`, all resolved within the organization and target account.
Service accounts use identity policies and trust, not human role assignments.

## Selecting an account role

The console's **Account role** menu chooses among your assigned roles.
Organization owners can use **Organization owner** for direct bootstrap
access or select an explicit role. Other users must select a role to use
account services.

The console keeps your personal organization session separate from the
selected account role session. Organization pages use your personal session;
account pages use the selected role. Changing account or organization clears
the previous role context. Expired role sessions are renewed from your personal
session, subject to current assignments and trust.

For integrations, use `GET /v1/account-roles` to discover a human's assignments,
then send the chosen role CRN to IAM's `POST /v1/assume-role`. Verify the
returned `account_id`, `account_handle`, and `role_id` before using the token.
Changing `X-Account-Id` does not change a token's account authority.

## Removing access and deleting accounts

Removing an assignment prevents new assumptions through that assignment.
Review and revoke existing sessions when ending active access; do not treat
assignment removal as a substitute for session revocation.

An account must be empty before deletion. Its roles, policies, service accounts,
and sessions count as account resources, along with infrastructure. Clean up
dependencies before deleting the account through Workspace.

For automated account cleanup, keep the original organization credential.
Remove resources using the account administrator role, delete that role last,
then delete the empty account with the organization credential. Deleting a role
also removes its sessions, so its current session cannot continue afterward.