Create client workspaces through a scoped provisioning workflow.

The provisioning key creates and configures workspaces inside one organization. It is structurally separate from the workspace key used later for contacts, campaigns, imports, and reporting.

Use two credentials for two jobs

A provisioning key cannot read routine client contact data. A workspace key cannot create another workspace. Each credential fixes its organization or workspace context. Callers cannot choose a different tenant ID.

1. Create a provisioning key

An organization admin creates the key from Developer API Keys and chooses workspaces:create, workspaces:configure, or both. Give the key a workload-specific name, use an expiry or source-IP restriction where appropriate, and store the one-time secret in the onboarding system's credential store.

2. Create the workspace idempotently

curl -X POST https://app.mailsequence.com/api/v1/provisioning/workspaces \
  -H "Authorization: Bearer $MAILSEQUENCE_PROVISIONING_KEY" \
  -H "Idempotency-Key: client-acme-workspace-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Acme Outbound",
    "config":{
      "domain_daily_send_limit":200,
      "unsubscribe_footer_enabled":true,
      "message_body_retention_days":90
    }
  }'

The organization is inferred from the key. The request must not include an organization ID. Workspace limits for the organization's plan are enforced before creation.

3. Capture the response once

A successful response contains the new workspace, its UUID, and a newly minted workspace-tier operating key. The operating secret is shown once. Store it against the new client record without writing it to logs, tickets, prompts, or the provisioning response archive.

4. Reapply approved settings safely

curl -X POST \
  https://app.mailsequence.com/api/v1/provisioning/workspaces/WORKSPACE_UUID/seed \
  -H "Authorization: Bearer $MAILSEQUENCE_PROVISIONING_KEY" \
  -H "Idempotency-Key: client-acme-seed-v2" \
  -H "Content-Type: application/json" \
  -d '{"config":{"domain_daily_send_limit":250}}'

The seed route is re-runnable and restricted to workspaces inside the key's organization. A foreign or missing UUID returns the same not-found response. Unknown configuration keys are rejected instead of silently ignored.

Current seedable settings

• Preferred AI provider and model.
• Domain daily sending limit.
• Unsubscribe-footer enablement.
• Message-body retention period from 1 to 3,650 days.

Provisioning does not connect domains or inboxes, import contacts, publish sequences, or launch campaigns by itself. Those activities require the appropriate workspace flow and credential.

5. Hand off to workspace operations

1. Record the workspace UUID and securely store the workspace key.
2. Invite or assign the client team through the appropriate role workflow.
3. Connect client-owned domains, inboxes, and provider accounts.
4. Import one controlled contact batch and reconcile the result.
5. Review infrastructure, audience, sequence, capacity, and ownership before launch.

Failure and recovery rules

• Use the same idempotency key and body when retrying an uncertain request.
• Use a new idempotency key when the requested configuration changes.
• Correct plan-cap, scope, validation, and tenant errors before retrying.
• Rotate or revoke the provisioning key independently of every workspace key it created.
• Audit which system and administrator created each client workspace.

Sources and product basis

• MailSequence public API reference
  Current provisioning request, response, scope, and validation contract.
• MailSequence for agencies
  Workspace isolation, organization operations, plan capacity, and migration model.
• Agency campaign QA checklist
  Operational review after provisioning and before launch.