# Account

A Koo account — the tenant/workspace identity: handle, tier, profile, and social counts.

**Attributes** (`AccountDto`)

- `id` · `string` · read-only — Account identifier.
- `handle` · `string` · required — Global-unique account handle — the URL/CLI slug.
- `tier` · `"Free" | "Plus" | "Pro" | "Enterprise"` · read-only — The account’s plan, by display name. The internal Free sub-tiers all report `Free`.
- `status` · `"active" | "suspended" | "pending_deletion" | "provisioning_pending" | "payment_pending"` · read-only — Account lifecycle status. `provisioning_pending`: the hosting environment is still being set up — deploys are paused until provisioning completes (retry via POST /accounts/:id/reprovision). `payment_pending`: a secondary account that has never been paid for — it has no hosting environment and every write is refused with 402 until a subscription starts.
- `deleteAt` · `string <date-time>` · read-only — Scheduled hard-delete time; set iff `status === 'pending_deletion'`.
- `isPrimary` · `boolean` · read-only — Whether this is the user's primary account (created during onboarding).
- `onboardingState` · `object` · read-only — The account's onboarding state machine position.
  - `step` · `"SIGNED_IN" | "HANDLE_PICKED" | "SOURCE_SELECTED" | "APP_CONFIGURED" | "MFA_VERIFIED" | "COMPLETED"` · read-only — Current step the account has reached in the onboarding state machine.
  - `cliDeploy` · `object` · read-only — Set once a `koo up` CLI deploy is detected during onboarding (see onboardingCliDeploySchema).
    - `projectId` · `string` · read-only — Project the CLI created/used.
    - `environmentId` · `string` · read-only — Environment the CLI deployed into.
    - `serviceId` · `string` · read-only — The archive-source web service the CLI shipped.
- `profile` · `object` · required — Editable account profile (avatar, banner, bio, location, links).
  - `displayName` · `string` · optional — Optional pretty name shown beside the handle. UIs fall back to the handle when unset.
  - `avatarUrl` · `string <uri>` · optional — Avatar image URL.
  - `bannerUrl` · `string <uri>` · optional — Profile banner image URL.
  - `bio` · `string` · optional — Free-text profile bio.
  - `location` · `string` · optional — Free-text location string.
  - `links` · `Record<string, string>` · optional — Map of label to URL for profile links.
- `counts` · `object` · read-only — Denormalized social/app counts for this account.
  - `followers` · `integer` · read-only — Number of accounts following this account.
  - `following` · `integer` · read-only — Number of accounts this account follows.
  - `apps` · `integer` · read-only — Number of active published apps owned by this account (the public "product" figure).
- `createdAt` · `string <date-time>` · read-only — Account creation timestamp.

**Example `AccountDto`**

```json
{
  "id": "acct_01example0000000000000000x",
  "handle": "alice",
  "tier": "Free",
  "status": "active",
  "deleteAt": "2026-01-01T00:00:00.000Z",
  "isPrimary": true,
  "onboardingState": {
    "step": "SIGNED_IN",
    "cliDeploy": {
      "projectId": "project_01example0000000000000000x",
      "environmentId": "environment_01example0000000000000000x",
      "serviceId": "svc_01example0000000000000000x"
    }
  },
  "profile": {
    "displayName": "My app",
    "avatarUrl": "https://example.com",
    "bannerUrl": "https://example.com",
    "bio": "example",
    "location": "example",
    "links": {
      "key": "example"
    }
  },
  "counts": {
    "followers": 0,
    "following": 0,
    "apps": 0
  },
  "createdAt": "2026-01-01T00:00:00.000Z"
}
```