Skip to main content
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
Read the Overview 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 for every field.
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.
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.
2

Store the token — it is shown exactly once

The 201 response carries a token:
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

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.
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.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
  • 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.