# Teams and roles

Every TaskCloud account is an **organization**. Sandboxes, API keys, webhooks, usage and billing belong to the organization, not to a person. People sign in to the web console and act inside one organization at a time; programs use [API keys](security.md).

## Sign-in

- **E-mail link:** enter your address in the console and open the link we send. It works once and expires in 15 minutes.
- **GitHub:** sign in with GitHub; we use your verified primary e-mail address, so the same person ends up in the same account either way.

Your first sign-in creates your account and a personal organization on the **Free** plan (20 h of `default` usage, once per person, 2 concurrent sandboxes, no card). Organizations you create later start on Free without the 20 h; upgrade them to Starter or Team from the console billing page.

The 20 h belong to a person, not to an address: aliases of one mailbox (for example `jane.doe+test@gmail.com` and `janedoe@gmail.com`) count once. If you sign up with a disposable e-mail domain, or many accounts were created from your network on the same day, the 20 h are **on hold** until you verify the account by adding a card (upgrading) or by signing in with a GitHub account that is more than 90 days old. New unverified accounts also have [stricter limits](limits.md) for their first 7 days.

Console sessions last 30 days from your last activity and at most 90 days from sign-in; then you sign in again. You can see and sign out your other sessions in the console.

## Two-factor authentication

Turn it on in **Settings → Security**: scan the QR code with an authenticator app (any app that supports TOTP: 1Password, Google Authenticator, Authy and others), enter a code, and save the 10 **recovery codes** we show once. Each recovery code works once if you lose your phone. From then on, signing in asks for a code after the e-mail link or GitHub. Turning 2FA off, creating new recovery codes and deleting your account also need a code. We e-mail you whenever 2FA is turned on or off or new recovery codes are created.

An owner who uses 2FA can **require two-factor authentication** for the whole organization (Settings → Organization). Members without 2FA can then still sign in and open Settings to turn it on, but cannot use the organization (`403`, `details.reason = "two_factor_required"`) until they do. API keys are not affected.

## Roles

| Action | Owner | Admin | Member |
| --- | :---: | :---: | :---: |
| Create, use and delete sandboxes, snapshots, templates; exec, files, SSH, desktop | ✓ | ✓ | ✓ |
| View usage, limits, members and the billing overview | ✓ | ✓ | ✓ |
| Create API keys (never with more access than your role) | ✓ | ✓ | ✓ |
| See, rotate and revoke **other people's** API keys | ✓ | ✓ | – |
| Manage webhooks and the spend limit | ✓ | ✓ | – |
| Invite people, revoke invitations, change roles, remove members | ✓ | ✓ (not owners) | – |
| Upgrade the plan, change the card (billing portal) | ✓ | ✓ | – |
| Rename the organization | ✓ | ✓ | – |
| Grant or take away the owner role, remove an owner | ✓ | – | – |
| Delete the organization | ✓ | – | – |
| Leave the organization | ✓ (not the last owner) | ✓ | ✓ |

An organization always keeps at least one owner. A member sees only the API keys they created. A request your role does not allow returns `403` with `"code": "forbidden"` and `details.reason = "insufficient_role"`.

## Invitations

Owners and admins invite people by e-mail from the console. The link is valid for 7 days and must be accepted while signed in with the invited address. Only an owner can invite another owner.

## Automating with API keys

An API key acts with its scopes in its organization. Keys with `account:read` can list members and invitations and read the billing overview; keys with `account:manage` can invite, change roles of admins and members, remove them and start a checkout. Keys cannot grant or remove the owner role.

```bash
curl -s https://api.task.cloud/v1/members -H "Authorization: Bearer $TASKCLOUD_API_KEY"

curl -s -X POST https://api.task.cloud/v1/invitations \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"email": "grace@example.com", "role": "member"}'
```

Removing someone revokes their access to the organization at once, **including the API keys they created** (sandboxes they created stay with the organization). A person's API key never has more access than the person: if an admin becomes a member, their keys lose admin-only scopes at once, and a member's key, like the member, sees only that member's keys. Keys created by another API key are not tied to a person.

Invitation e-mails are limited to 20 per organization per hour and 3 per address per organization per day. Organization names cannot contain links or e-mail addresses.

## Deleting an organization

An owner can delete an organization in the console (Settings → Danger zone) once it has no sandboxes left, paused ones included, and no paid subscription (cancel it in the billing portal first). You cannot delete your only organization. Deleting revokes the organization's API keys and open invitations and removes it for every member. We never delete sandboxes for you as part of this step, because deleting a disk cannot be undone.

30 days after the deletion we purge the rest: named snapshots, custom templates, member and invitation data. The organization's encryption keys for stored snapshots are destroyed, so snapshot data still in storage can no longer be read. Usage records and invoices are kept for accounting.

## Your personal data and deleting your account

**Settings → Danger zone → Export my data** downloads a JSON file with your profile, organizations and roles, sessions (with IP addresses), two-factor status, invitations you sent, API keys you created (never their secrets) and the audit records about you (`GET /v1/me/export`).

**Delete account** erases your user: profile, sessions, memberships and two-factor settings. Type your e-mail address to confirm (and a 2FA code if you use it). Organizations where you are the only member are deleted with your account. You cannot delete your account while you are the only owner of an organization that has sandboxes, a paid subscription or other members: delete the sandboxes, cancel the subscription or make someone else owner first. Audit records we must keep stay, but your user ID in them is replaced by a pseudonym and their details (such as IP addresses) are removed. You can sign up again with the same address later; it will be a new, empty account.