Skip to main content
A user is a person with a personal sign-in. Users belong to the organization through Workspace. Unattended programs use an account service account or role. Users belong to an organization, not to an account. A user reaches account resources through assigned account roles. Organization policies grant organization permissions, not account resource access.

Adding a user

Why this is always an invitation, and what a 201 does not promise.

Groups

Organization policies and account role assignments for a team of users.

Removing a user

What it detaches, what it leaves behind, and when it takes effect.

​
Adding a user

Open Organization → Users, then Invite users. Enter one or more Email addresses and optionally select Groups. Each address receives its own invitation; the results show which invitations succeeded.Pending invitations are listed on the Users page with a Cancel invitation action.
email is the only required field. groups is the useful one: it puts the person in their groups at the moment they join, so there is no window where they exist with no permissions and someone has to remember to fix it.
This call always creates an invitation, never a user. The response is the invitation, and the person becomes a user when they accept it — including when they already have a Basaltic login. There is no path that adds someone to an organization without their consent.Until they accept they are a row on the pending-invitations list, not on Users.
It is refused with 409 in two cases, which are worth telling apart:
A 201 means the invitation was created, not that the email arrived. Sending is best-effort: if the mail fails the invitation still exists and the request still succeeds, because losing an invitation that was already recorded would be worse.So “they never got the email” is a real state, and the fix is to cancel the pending invitation and add them again rather than to wait.

​
Invitations

An invitation records its actual inviter. invited_by.type distinguishes a user, service account, or assumed-role session; machine inviters also include their account identity and do not have a human email address. An invitation is the pending half of the call above. There is no separate “create invitation” endpoint on the public API — you add a user, and an invitation is what you get when they do not exist yet.
Pending invitations are listed on Organization → Users, below the users, with Cancel invitation on each row. When there are none the section reads “No pending invitations.”
Cancelling an invitation is not the same as removing a user: it withdraws an offer nobody has accepted. Once accepted, use remove instead.

​
Groups

A group collects principals and holds policies. Attaching a policy to a group rather than to each member is the difference between one change and n changes when the team’s permissions move.
Open Organization → Groups and choose Create Group. Enter a Name and an optional Description.The group’s Users and Policies tabs manage its user members and organization policy attachments.
Groups contain users only and do not nest. Service accounts and roles use separate account policy and organization policy attachments. A user’s organization permissions include policies attached directly and through their groups. An account role assignment to a group lets its members request that role; its trust policy must still accept each assuming user.

​
Where to attach a policy

Attach organization policies to groups when the grant describes a team or job. Use direct user attachments for individual exceptions. Account permissions belong on roles and service accounts, not on users or groups. Inline policies are a third option and a narrower one — see managed and inline policies.

​
Removing a user

Open the user, choose Settings, then Remove user in the danger zone. Type the displayed confirmation value before confirming.
Removing a user takes them out of this organization. It does not delete their Basaltic login, which may belong to other organizations, and it does not delete anything they created — resources belong to the account, not to the person who made them. The removal is atomic and takes their whole footprint in this organization with it: group memberships, policy attachments, inline policies, their permission boundary, and finally the membership itself.
That means re-adding the same email later produces a user with no permissions — none of it comes back. If you are removing someone temporarily, write down which groups they were in first: nothing else does.
Removal ends membership in this organization. Review the user’s role sessions as part of offboarding; the account STS session pages show the source principal and allow explicit revocation.

​
Permissions

These APIs use https://workspace.basaltic.sh. Their actions are in the workspace: namespace and must be granted through organization policies. See Workspace permissions for the resource checks and account role assignment actions.

​
Next

Service accounts and roles

The identities that are not people.

Writing policies

What goes in the document you attach here.