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

# Add a client

> Create a workspace for a client, with an API key that can reach only it.

The client gets their own workspace and a key scoped to it. They never sign up to Orgo: your app uses the key on their behalf. The key is in this response only, so store it with your user.

Use your account-wide API key. A client’s own key gets `403` here. See [Invoicing](/guides/invoicing).

## Body

<ParamField body="name" type="string">
  Shown in Settings. Send this, `external_id`, or both.
</ParamField>

<ParamField body="external_id" type="string">
  Your id for this client, unique among your clients. Made from `name` when you leave it out.
</ParamField>

<ParamField body="max_computers" type="integer">
  The most computers they can have. No limit when left out.
</ParamField>

<ParamField body="monthly_ai_cap_usd" type="number">
  Their AI stops at this amount each month. No limit when left out.
</ParamField>

## Response

<ResponseField name="api_key" type="string">
  The client’s key. Shown once.
</ResponseField>

Every field of [Get client](/api-reference/clients/get).

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.orgo.ai/api/v1/accounts \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "Acme Dental", "external_id": "acme-dental"}'
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.post(
      f"https://www.orgo.ai/api/v1/accounts",
      headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
      json={"name": "Acme Dental", "external_id": "acme-dental"},
  )
  print(res.json())
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(`https://www.orgo.ai/api/v1/accounts`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({"name": "Acme Dental", "external_id": "acme-dental"}),
  });
  console.log(await res.json());
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "8f14e45f-ceea-467a-9575-6f1c2b3d4e5f",
  "external_id": "acme-dental",
  "name": "Acme Dental",
  "status": "active",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-10-01T09:00:00Z",
  "closed_at": null,
  "limits": {
    "max_computers": null,
    "monthly_ai_cap_usd": null
  },
  "usage": {
    "computers": 0,
    "ai_spend_usd_this_month": 0
  },
  "billing": null,
  "transfer": null,
  "api_key": "sk_live_…"
}
```

## Errors

| Status | Body | Meaning |
| - | - | - |
| `401` | `{ "error": "Invalid API key" }` | No key, or not one of yours. |
| `403` | `{ "error": "Use your account-wide API key to manage accounts. Workspace keys can’t." }` | A client’s own key, or any key scoped to one workspace. |
| `403` | `{ "error": "Invoicing is on every paid plan. Upgrade to use it." }` | You’re on the Free plan. `code` is `UPGRADE_REQUIRED`. |
| `400` | `{ "error": "Send a name, an external_id, or both." }` | Neither was sent. |
| `409` | `{ "error": "An account with external_id "acme-dental" already exists." }` | `code` is `ACCOUNT_EXISTS`. |


## OpenAPI

````yaml POST /v1/accounts
openapi: 3.1.0
info:
  title: Orgo API
  description: >-
    Launch cloud computers that AI agents can control and interact with. Create
    workspaces, provision computers, and control them programmatically.
  version: 2.0.0
  contact:
    name: Orgo Support
    email: spencer@orgo.ai
    url: https://orgo.ai
servers:
  - url: https://www.orgo.ai/api
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account capacity: how many computers an account may run, and adding or
      giving back more.
  - name: Clients
    description: >-
      Run Orgo for your clients from your own app: a workspace and scoped key
      each, billed to you or to them.
  - name: Workspaces
    description: Organize computers into named workspaces
  - name: Computers
    description: Provision and manage virtual computers
  - name: Computer Lifecycle
    description: Start, stop, and restart computers
  - name: Computer Actions
    description: Control mouse, keyboard, and execute commands
  - name: Screens
    description: >-
      More than one desktop on a single computer. Each screen is its own X
      server with its own cursor and window manager, so an agent working on one
      cannot disturb another.
  - name: Files
    description: Upload and download files
  - name: Templates
    description: Author, build, and launch reproducible computers from templates
paths:
  /v1/accounts:
    post:
      tags:
        - Clients
      summary: Add a client
      description: Create a workspace for a client, with an API key that can reach only it.
      operationId: createClient
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Shown in Settings. Send this, `external_id`, or both.
                external_id:
                  type: string
                  description: >-
                    Your id for this client, unique among your clients. Made
                    from `name` when you leave it out.
                max_computers:
                  type: integer
                  description: The most computers they can have. No limit when left out.
                monthly_ai_cap_usd:
                  type: number
                  description: >-
                    Their AI stops at this amount each month. No limit when left
                    out.
            example:
              name: Acme Dental
              external_id: acme-dental
      responses:
        '201':
          description: Created
          content:
            application/json:
              example:
                id: 8f14e45f-ceea-467a-9575-6f1c2b3d4e5f
                external_id: acme-dental
                name: Acme Dental
                status: active
                workspace_id: 550e8400-e29b-41d4-a716-446655440000
                created_at: '2026-10-01T09:00:00Z'
                closed_at: null
                limits:
                  max_computers: null
                  monthly_ai_cap_usd: null
                usage:
                  computers: 0
                  ai_spend_usd_this_month: 0
                billing: null
                transfer: null
                api_key: sk_live_…
              schema:
                $ref: '#/components/schemas/ClientWithKey'
        '400':
          description: Neither was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: Neither was sent
                  value:
                    error: Send a name, an external_id, or both.
        '401':
          description: No key, or not one of yours.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: No key, or not one of yours
                  value:
                    error: Invalid API key
        '403':
          description: >-
            A client’s own key, or any key scoped to one workspace. You’re on
            the Free plan. `code` is `UPGRADE_REQUIRED`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: A client’s own key, or any key scoped to one workspace
                  value:
                    error: >-
                      Use your account-wide API key to manage accounts.
                      Workspace keys can’t.
                e2:
                  summary: You’re on the Free plan
                  value:
                    error: Invoicing is on every paid plan. Upgrade to use it.
        '409':
          description: '`code` is `ACCOUNT_EXISTS`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                e1:
                  summary: '`code` is `ACCOUNT_EXISTS`'
                  value:
                    error: An account with external_id "acme-dental" already exists.
components:
  schemas:
    ClientWithKey:
      allOf:
        - $ref: '#/components/schemas/Client'
        - type: object
          properties:
            api_key:
              type: string
              description: Shown once.
    Error:
      type: object
      description: >-
        The base error body. Every failure carries `error`; individual endpoints
        add the fields named in the schemas below.
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable message.
          example: Access denied
        code:
          type: string
          description: >-
            Machine-readable reason. Present on the failures that define one,
            absent otherwise.
    Client:
      type: object
      description: 'A client: a workspace you run for them, with a key scoped to it.'
      properties:
        id:
          type: string
        external_id:
          type: string
        name:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - active
            - closed
            - transferred
        workspace_id:
          type: string
        created_at:
          type: string
          format: date-time
        closed_at:
          type: string
          format: date-time
          nullable: true
        limits:
          type: object
          properties:
            max_computers:
              type: integer
              nullable: true
            monthly_ai_cap_usd:
              type: number
              nullable: true
        usage:
          type: object
          properties:
            computers:
              type: integer
            ai_spend_usd_this_month:
              type: number
        billing:
          type: object
          nullable: true
          properties:
            status:
              type: string
              enum:
                - sent
                - active
                - past_due
            price_usd:
              type: number
            email:
              type: string
        transfer:
          type: object
          nullable: true
          properties:
            email:
              type: string
            sent_at:
              type: string
              format: date-time
        computers:
          type: array
          description: On Get client only.
          items:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your key at orgo.ai/workspaces

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.