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

# Workspace

> Organizations, accounts, people, and organization permissions.

Workspace manages your organization: its accounts, users, groups, invitations,
and organization policies. Its API is global at `workspace.basaltic.sh`.
Personal sign-in and token exchange remain on `iam.basaltic.sh`.

An organization contains accounts. Each account owns its infrastructure and its
[IAM roles, service accounts, policies, and sessions](/iam). A region chooses
where regional resources run; it does not change which account owns them.
DNS and IAM are global services with account-owned resources.

| Scope             | Resources                                                              | Console location                     |
| ----------------- | ---------------------------------------------------------------------- | ------------------------------------ |
| Organization      | Accounts, users, groups, invitations, organization policies            | Workspace → Organization             |
| Account, global   | IAM roles, service accounts, account policies, STS sessions; DNS zones | The selected account's service pages |
| Account, regional | Instances, volumes, networks, and other regional resources             | The selected account and region      |

The console shows **Organization scope** on organization pages and **Global**
on global account services. Returning to a regional service restores the
selected region.

<CardGroup cols={2}>
  <Card title="Users and groups" icon="users" href="/iam/users">
    Invite people, organize teams, and grant organization permissions.
  </Card>

  <Card title="Account access" icon="folder" href="/workspace/accounts">
    Create an account and give people access through roles.
  </Card>

  <Card title="Organization permissions" icon="key" href="/workspace/permissions">
    Workspace actions and delegation to account identities.
  </Card>

  <Card title="Policy documents" icon="file-text" href="/iam/policies">
    The shared policy language for account and organization policies.
  </Card>
</CardGroup>

## Two policy scopes

Organization policies grant `workspace:*`, `billing:*`, `quota:*`, and
`audit:*` actions. Attach them to users or groups for human organization work,
or explicitly delegate them to a role or service account for automation.

Account policies grant account service actions, such as `iam:*`, `compute:*`,
`dns:*`, and `storage:*`. Attach them to roles and service accounts in that
account. Even an account policy allowing `*` cannot grant organization access.
Organization policies do not grant ordinary account service access.

A user or group receives account access through a role assignment. The user
then assumes that role, subject to its trust policy. An organization owner
retains direct account access for setup and recovery and can also choose a role.

## Automation that manages the organization

A billing collector can use an account service account or an instance role.
Attach an organization policy allowing only the billing reads it needs. An
employee onboarding job can instead receive a policy for inviting users,
managing groups, and assigning account roles.

The role or service account shows separate **Account policies** and
**Organization policies** tables. The organization grant is explicit and
reviewable; an account administrator cannot obtain it by editing an account
policy. Granting organization access requires both organization delegation
permission and permission to update the target identity in its account.
See [delegating organization policies](/workspace/permissions#delegating-organization-policies).

## Organization resource names

Organization resources carry the organization UUID in their CRN:

```
crn:workspace:::organization/<organization-uuid>
crn:workspace:::organization/<organization-uuid>/account/<account-uuid>
crn:workspace:::organization/<organization-uuid>/user/<user-uuid>
crn:workspace:::organization/<organization-uuid>/group/platform-team
crn:workspace:::organization/<organization-uuid>/policy/billing-reader
```

System organization policies use `crn:workspace:::policy/<Name>`. The UUID in
an organization CRN identifies the organization explicitly; it does not grant
access to another organization.

## Updating existing integrations

Organization administration now uses Workspace. Keep personal authentication
on IAM and move organization resource calls to `workspace.basaltic.sh`:

| Resource                                                | API service | Permission namespace |
| ------------------------------------------------------- | ----------- | -------------------- |
| Organizations, accounts, users, groups, invitations     | Workspace   | `workspace:`         |
| Organization policies and their attachments             | Workspace   | `workspace:`         |
| Account roles, service accounts, policies, and sessions | IAM         | `iam:`               |

The organization resource paths retain their `/v1` collection names. Account
IAM requests require a selected account that agrees with the credential.
Refresh stored resource references from API responses: organization resources
now have Workspace CRNs and account IAM resources include their account handle.
Shared system policies have an empty account slot, not a `platform` account.

Remove service-account group management from integrations. Grant a machine
identity account policies directly and delegate organization policies explicitly.
Human account access uses role assignments followed by AssumeRole.