Tenant Onboarding

This guide is for Platform Engineers onboarding a new retail chain onto the RSA Platform. Requires a platform.write scoped token.

Step 1: Create the Tenant

curl -X POST "http://localhost:5004/platform/api/v1/tenants" \
  -H "Authorization: Bearer PLATFORM_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cardenas Markets",
    "planTier": "Enterprise",
    "adminEmail": "admin@cardenas.com"
  }'

Response (201 Created):

{
  "tenantId": "c1d2e3f4-...",
  "slug": "cardenas",
  "status": "Trial",
  "invitationSent": true
}

An invitation email is sent to adminEmail. The tenant admin accepts the invite and sets up MFA before accessing the Admin Portal.

Step 2: Provision a Retailer Database

curl -X POST "http://localhost:5004/platform/api/v1/tenants/c1d2e3f4-.../retailers" \
  -H "Authorization: Bearer PLATFORM_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cardenas Banner A",
    "slug": "cardenas-a"
  }'

Response (202 Accepted):

{
  "jobId": "job-uuid",
  "slug": "cardenas-a",
  "status": "Provisioning"
}

This is an async operation — the platform is creating a SQL Server database and running migrations.

Step 3: Poll Provisioning Status

# Poll until status is "Ready"
curl "http://localhost:5004/platform/api/v1/retailers/cardenas-a/status" \
  -H "Authorization: Bearer PLATFORM_JWT"

{
  "slug": "cardenas-a",
  "status": "Ready",    // or "Provisioning" | "Failed"
  "provisionedAt": "2026-05-24T10:30:00Z"
}

Step 4: Enable Tenant Features

Enable platform-level features for the tenant:

curl -X PUT "http://localhost:5004/platform/api/v1/tenants/c1d2e3f4-.../features/fuel-offers" \
  -H "Authorization: Bearer PLATFORM_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Step 5: Set Tenant Branding

curl -X PUT "http://localhost:5004/platform/api/v1/tenants/c1d2e3f4-.../branding" \
  -H "Authorization: Bearer PLATFORM_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "logoUrl": "https://cdn.cardenas.com/logo.png",
    "primaryColor": "#e63946",
    "supportEmail": "support@cardenas.com"
  }'

Step 6: Transition to Active

Once the tenant admin has set up their account and confirmed readiness:

curl -X PUT "http://localhost:5004/platform/api/v1/tenants/c1d2e3f4-.../lifecycle" \
  -H "Authorization: Bearer PLATFORM_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "state": "Active" }'

The tenant is now fully active and the Admin Portal is accessible to the tenant admin.