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

# Onboard a Client

> Provision a Penbox workspace for one of your clients, store its token, and register their team — in three calls.

Your client signs up in your product. This guide turns that into a fully configured Penbox
workspace, with no manual step on either side.

## What you'll have

By the end of this guide:

* A Penbox workspace for that client, seeded with your case templates
* An API token scoped to it, stored on your side
* Your client's team registered, ready to own cases and receive tasks

**Estimated time:** 10 minutes

<Info>
  Read the [Overview](/guides/headless-overview) first — it names the five actors and the auth
  header every call below uses.
</Info>

***

<Steps>
  <Step title="Provision the workspace">
    One call creates the workspace, registers its admins, copies your case templates into it, and
    returns a token scoped to it. See
    [Provision Workspace](/api-reference/workspaces/provision-workspace) for every field.

    ```bash theme={null}
    curl --request POST \
      --url https://connect.penbox.io/v1/workspaces \
      --header 'Authorization: Bearer <your-key>' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Acme",
        "admin": { "email": "admin@acme.example" },
        "template_source": { "case_template_ids": ["<template-uuid>"] },
        "integration": { "legalops": { "source_workspace_id": "acme-42" } }
      }'
    ```

    The call is **idempotent** on `source_workspace_id` — your own identifier for that client. A
    `201` means the workspace was created; replaying the same call returns the existing workspace
    with a `200` and no token. It also never fails halfway: an optional step that could not
    complete (a template that no longer exists, for instance) is reported in a `warnings` array,
    not as an error. Log the warnings.

    Omit `template_source` entirely and **all** the case templates of your own workspace are
    copied — treat your workspace as the template matrix for every client you provision.

    <Note>
      **Two admins are created here, both silent.** The `admin` you send is your client's, so
      someone on their side formally owns the workspace. Penbox also adds **your own support
      account**, so your team can help them while the workspace stays headless. That address is
      configured once with Penbox on your partner workspace — it is never sent in this payload. If
      it is missing, provisioning still succeeds and tells you so in `warnings`.

      Silent means Penbox never emails them. Your users never hear from Penbox, and never see a
      Penbox screen, unless you decide otherwise.
    </Note>
  </Step>

  <Step title="Store the token — it is shown exactly once">
    The `201` response carries a `token`:

    ```json theme={null}
    {
      "workspace": { "id": "…", "name": "Acme", "slug": "acme" },
      "token": "pnbx_0f1e2d3c4b5a69788796a5b4c3d2e1f001122334455…"
    }
    ```

    Penbox stores only its hash and can never show it again. Persist it before anything else: it is
    the only secret you keep per client, and every call in the next guides uses it.
  </Step>

  <Step title="Register your client's team">
    The two admins from step 1 already exist — do not re-create them. What is left is everyone who
    will actually **own cases and receive tasks**. Add them one call each, with
    [Create Member](/api-reference/members/create-member).

    ```bash theme={null}
    curl --request POST \
      --url https://connect.penbox.io/v1/members \
      --header 'Authorization: Bearer <token>' \
      --header 'Content-Type: application/json' \
      --data '{
        "workspace": { "id": "<workspace-uuid>" },
        "email": "amina@acme.example",
        "given_name": "Amina"
      }'
    ```

    People added here are **Handlers**: they work on cases and forms, and cannot change workspace
    settings. Send `"is_handler": false` instead for someone who should only see what they are
    assigned. The three roles are described in [Members](/workspace/settings/members).

    Like provisioning, the call is idempotent — on the email this time — and members created
    through the API are always silent. Call it again whenever your client hires someone; there is
    no batch to prepare up front.
  </Step>
</Steps>

## You've onboarded a client

Three calls in, this client now has:

* A Penbox workspace, seeded with your case templates
* A token scoped to it, stored on your side
* Two silent admins — your client's owner and your own support account
* Their team registered as Handlers, ready to own cases

Nobody was emailed. Nobody opened Penbox. Repeat these three calls for every client you sign, and
onboarding costs you zero manual steps.

**Next:** [Create a case on the fly](/guides/headless-create-case).