How to Onboard a Tenant

Who This Guide Is For

Use this page when you need to take a brand-new tenant from "no workspace exists yet" to "the team can send REST and webhook traffic without asking for manual help".

It covers two actors:

1. Admin / super admin creates the tenant, adds the first user, and prepares initial credentials.
2. Tenant team signs in, retrieves the API key, configures webhook settings, and verifies the first requests.

If the tenant already exists and you only need credentials, jump to Tenant first login.

Target Outcome

After this flow:

• the tenant exists in Backoffice,
• at least one tenant user can log in,
• the team has an API key,
• the team knows where to configure callback URL and secrets,
• one sample REST request and one sample webhook are visible in Backoffice.

Admin Setup Flow

1. Create the tenant

In Backoffice:

1. Open Tenants.
2. Create a new tenant record.
3. Fill the minimum canonical fields:
   • tenant name
   • slug
   • active plan
   • business time zone
4. Save the tenant before moving on.

What to decide at creation time:

• the tenant slug should be stable and URL-safe,
• the time zone should match the tenant's billing and operations reality,
• the initial plan should match expected launch traffic, not just today's tiny test volume.

2. Add the first tenant user

Still in Backoffice:

1. Open the tenant.
2. Add the first tenant-scoped user.
3. Use the real operator email, not a shared mailbox if you can avoid it.
4. Make sure the role is tenant-scoped, not admin, unless this is an internal platform operator.

The first tenant user should be someone who can:

• retrieve credentials,
• configure callbacks,
• run first integration tests,
• confirm expected payloads on their own side.

3. Prepare the initial API key

Before handing the tenant off:

1. Open the tenant API Keys section.
2. Either:
   • create the first key yourself, or
   • leave key creation to the tenant user if that workflow is allowed for them.
3. Label the key clearly:
   • production
   • staging
   • integration-test

Do not hand off an unlabeled key if multiple environments will exist quickly. That causes avoidable support noise later.

4. Decide the initial webhook shape

Before the tenant starts integration, align on:

• callback URL they will use,
• provider adapters they need first:
  • Stripe
  • Shopify
  • GitHub
  • Generic HMAC
• whether they will use API key routes or slug routes for inbound webhooks.

This avoids the common failure mode where the tenant has credentials but no clear first callback target.

5. Send the handoff packet

Minimum handoff packet:

• Backoffice URL
• tenant user login email
• whether password or reset flow was prearranged
• API key or instructions for generating it
• which environments are expected first
• which webhook provider is expected first
• links:
  • Quickstart
  • Auth / Keys
  • Webhook Gateway
  • Backoffice Overview

Tenant First Login

1. Sign in to Backoffice

1. Open the Backoffice URL you received.
2. Sign in with your tenant user account.
3. Confirm that you only see your own tenant data.

Expected result:

• you can open your tenant home,
• you can see API keys,
• you can see webhook settings and event history,
• you do not see cross-tenant admin surfaces unless your role explicitly allows it.

2. Retrieve or create the API key

1. Open the tenant API Keys section.
2. Copy the key you will use for the first integration.
3. Store it securely.

Use it as:

Authorization: Bearer <API_KEY>

If your team uses multiple environments, keep separate keys per environment and label them immediately.

3. Verify the first REST integration path

Your first successful REST test should be a /v1/record flow, not production business traffic.

Use the steps in:

• Quickstart
• Idempotency
• Idempotent Records API

Goal of the first test:

• confirm auth works,
• confirm the key resolves to the right tenant,
• confirm you understand lock -> save -> get.

4. Configure webhook settings

1. Open Webhooks in Backoffice.
2. Pick the provider you are integrating first.
3. Set:
   • callback URL
   • provider secret or signing secret
4. Copy the inbound Syllecta webhook URL shown in the UI.

Use these follow-up guides:

• Webhook Gateway
• Webhooks API
• provider examples under /docs/examples/*

5. Send one test webhook

Do not start with a full production replay. Start with one controlled event.

Expected result:

• event appears in Webhooks -> Events
• status reaches processed
• your downstream callback receives the forwarded payload

If it fails:

• check provider secret and callback URL first,
• then inspect the event row and delivery status in Backoffice.

Recommended First-Day Checklist

Admin checklist

• Tenant exists with correct slug and time zone.
• First tenant user exists and can sign in.
• At least one labeled API key exists.
• Initial webhook provider and callback plan are agreed.
• Tenant received the handoff packet with the right docs links.

Tenant checklist

• Backoffice login works.
• API key is stored securely.
• First /v1/record test succeeds.
• First webhook test appears in Backoffice.
• Team knows where to inspect usage counters and event history.

Verification in Backoffice

After the first integration pass, confirm these places:

1. Tenant home
   • plan and billing status look correct
   • usage counters move after sample traffic
2. API Keys
   • only expected keys exist
   • labels match environment usage
3. Webhooks -> Events
   • test webhook is present
   • status and callback behavior match expectations
4. Audit Logs for admin users
   • key creation, settings changes, and retries are visible

Common Avoidable Mistakes

Reusing one key across all environments

This makes rollout harder to debug and rotate later. Use separate keys and labels.

Leaving callback URL unset during the first webhook test

The tenant can send events into Syllecta, but nothing useful gets forwarded downstream.

Using the wrong time zone

This creates confusing billing and reporting behavior later, especially around daily and monthly boundaries.

Starting with full provider replay

Always start with one or two controlled events. It is easier to validate signatures, payload shape, and callback behavior that way.

Related Guides

• Quickstart
• Backoffice Overview
• Idempotency
• Webhook Gateway
• Auth / Keys
• Idempotent Records API
• Webhooks API

This is the minimum onboarding path that should get a new tenant to first successful traffic without ad-hoc support intervention.