> ## 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

> [!NOTE]
>
> Read the [Overview](https://docs.penbox.io/guides/headless-overview.md) first — it names the five actors and the auth
> header every call below uses.

***

**1. 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](https://docs.penbox.io/api-reference/workspaces/provision-workspace.md) 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": { "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]
>
> **One admin is created here, silent.** The `admin` you send is your client's, so someone on
> their side formally owns the workspace. Your own support account is yours to add, in step 3.
>
> Silent means Penbox never emails them. Your users never hear from Penbox, and never see a
> Penbox screen, unless you decide otherwise.

> [!NOTE]
>
> Provisioning is reserved to partner accounts — talk to Penbox to have yours enabled, or the
> call is rejected with a `401`. And **you pay for the workspaces you provision**: each one
> shares your billing account, so its credit usage is invoiced to you.

**2. 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.

**3. Register your client's team**

Your client's admin from step 1 already exists — do not re-create it. What is left is everyone
who will actually **own cases and receive tasks**, and your own support account. Add them one
call each, with [Create Member](https://docs.penbox.io/api-reference/members/create-member.md).

```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](https://docs.penbox.io/workspace/settings/members.md).

For your own support account, send `"is_admin": true`, so your team can help the client while
the workspace stays headless. If the client disconnects you, the admins you added are removed.

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.

## 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
* A silent admin — your client's owner — plus 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](https://docs.penbox.io/guides/headless-create-case.md).


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