Platform Admin
Tenant Provisioning
Create and manage tenants under a platform — including users, webhook config, and API keys.
A Tenant is a single customer workspace (e.g. Acme Corporation). All interviews, users, and API keys are isolated per tenant. Tenants are created by either a SuperAdmin or a Platform Admin.
Who Can Create Tenants
| Actor | Method | Endpoint |
|---|---|---|
| SuperAdmin | JWT from /super-admin/auth/login | POST /api/v1/tenants |
| Platform Admin | JWT from /platform-admin/auth/login | POST /api/v1/platform-admin/tenants |
The Platform Admin login is at the /login page under the Platform Admin tab — not at a separate
/platform-admin/login URL.Step 1 — Create a Tenant
| Field | Type | Required | Constraints |
|---|---|---|---|
| platformId | UUID | Yes | Must reference a valid Platform |
| name | string | Yes | Max 255 chars. Human-readable company name. |
| domain | string | Yes | Valid domain, globally unique. E.g. acme.com |
| adminEmail | string (email) | No | Optional. Used to associate an admin user at creation. |
bash
curl -X POST https://mayaapi.teamcast.ai/api/v1/tenants \
-H "Authorization: Bearer <superadmin_token>" \
-H "Content-Type: application/json" \
-d '{
"platformId": "c2650bb0-49b5-438a-b4d0-f9049ccb9f8a",
"name": "Acme Corporation",
"domain": "acme.com",
"adminEmail": "admin@acme.com"
}'Response 201
{
"id": "tenant-uuid",
"platformId": "c2650bb0-49b5-438a-b4d0-f9049ccb9f8a",
"name": "Acme Corporation",
"domain": "acme.com",
"status": "ACTIVE",
"createdAt": "2026-03-20T10:15:00.000Z"
}Step 2 — Create a Tenant Admin User
Tenant users (recruiters, admins) log in to the Tenant Admin zone at /login. Roles are ADMIN, RECRUITER, and USER.
bash
curl -X POST https://mayaapi.teamcast.ai/api/v1/users \
-H "Authorization: Bearer <superadmin_or_tenant_admin_token>" \
-H "Content-Type: application/json" \
-d '{
"email": "recruiter@acme.com",
"password": "<your_password>",
"name": "Jane Smith",
"role": "RECRUITER"
}'The token must belong to a user with
user:create permission, or be a SuperAdmin token. The created user is automatically scoped to the caller's tenant.Step 3 — Configure Webhook Delivery
The webhook config tells the system where to deliver event notifications for this tenant. Configure it once — the URL is not passed per interview request.
| Field | Type | Required | Description |
|---|---|---|---|
| callbackUrl | HTTPS URL | Yes | Your endpoint that receives POST requests. Must be HTTPS. RFC-1918/localhost blocked. |
| events | string[] | Yes | Events to subscribe to (see table below) |
| autoApprovePlans | boolean | No | Skip the manual plan approval gate. Default: false. |
| retentionDays | number | No | Days to retain interview data before auto-purge. Null = no auto-purge. |
| secret | string (hex) | No | HMAC-SHA256 signing secret. Auto-generated if omitted. Min 32 chars, hex-encoded. |
| Event | When Fired |
|---|---|
| interview.info_needed | Critical data is missing — PATCH .../info to supply it |
| interview.info_completed | Missing info was supplied; plan generation starting |
| interview.plan_generated | AI plan is ready and awaiting approval (state: PENDING) |
| interview.approved | Plan approved; interviewLink returned |
| interview.rejected | Plan rejected by recruiter |
| interview.modification_requested | Revision requested; plan regenerating |
| interview.assessment_pending | Interview complete; assessment awaiting verdict |
| interview.assessment_completed | Assessment approved; full report delivered |
bash
curl -X PUT https://mayaapi.teamcast.ai/api/v1/tenants/{TENANT_ID}/webhook-config \
-H "Authorization: Bearer <token_with_tenant:update>" \
-H "Content-Type: application/json" \
-d '{
"callbackUrl": "https://api.acme.com/webhooks/interview",
"events": [
"interview.info_needed",
"interview.info_completed",
"interview.plan_generated",
"interview.approved",
"interview.rejected",
"interview.assessment_pending",
"interview.assessment_completed"
],
"autoApprovePlans": false,
"retentionDays": 90
}'Response 200
{
"id": "config-uuid",
"tenantId": "tenant-uuid",
"callbackUrl": "https://api.acme.com/webhooks/interview",
"events": ["interview.info_needed", "interview.plan_generated", "interview.approved", "interview.assessment_pending", "interview.assessment_completed"],
"autoApprovePlans": false,
"retentionDays": 90,
"secretMasked": "****abcd",
"createdAt": "2026-03-20T10:20:00.000Z"
}The HMAC signing secret is shown as
secretMasked (last 4 chars only) after creation. Store the full secret at creation time — you cannot retrieve it later. To rotate: call the same endpoint again with a new secret value; old secret is invalidated immediately.Tenant Management (Platform Admin)
Platform Admins can manage tenants under their own platform after logging in at /login → Platform Admin tab.
Tenant lifecycle — activate & deactivate
Tenants are never hard-deleted. A Platform Admin can deactivate a tenant (sets status: INACTIVE) and activate it again (sets status: ACTIVE) at any time from the Tenants table — the row action toggles between a pause and a play control depending on the tenant's current state. Deactivated tenants stay visible in the list so they can be reactivated.
Deactivation takes effect immediately: the tenant's users, platform API-key calls carrying its X-Tenant-ID, and any OAuth integrations scoped to it are all blocked on their very next request — even tokens issued before deactivation. No interviews, plans, assessments, users, or audit history are removed; everything is preserved and comes back intact on reactivation.
The legacy
DELETE /platform-admin/tenants/{id} endpoint is now a soft alias for deactivate — it sets INACTIVE rather than removing data. New integrations should call PATCH .../deactivate and PATCH .../activate directly.Webhook delivery also stops while a tenant is deactivated. No event (
interview.plan_generated, interview.assessment.completed, etc.) is delivered to any endpoint — tenant-level, platform-level, or per-interview override — until the tenant is reactivated. Events that fire during the deactivated window are not queued for later replay.While a tenant is deactivated, a Platform Admin can still view it but cannot perform other mutations against its resources — only the activate/deactivate actions are permitted. A Super Admin is unrestricted: they can perform any action on any tenant regardless of status, and can activate or deactivate tenants across all platforms via
PATCH /super-admin/tenants/{id}/{activate,deactivate}.bash
curl -X POST https://mayaapi.teamcast.ai/api/v1/platform-admin/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@linkedin.com",
"password": "<your_password>"
}'Platform Admin Capabilities Summary
| Action | Endpoint |
|---|---|
| Login | POST /api/v1/platform-admin/auth/login |
| Get profile | GET /api/v1/platform-admin/auth/me |
| Platform stats | GET /api/v1/platform-admin/stats |
| List tenants | GET /api/v1/platform-admin/tenants |
| Create tenant | POST /api/v1/platform-admin/tenants |
| Update tenant | PUT /api/v1/platform-admin/tenants/{id} |
| Deactivate tenant (soft) | PATCH /api/v1/platform-admin/tenants/{id}/deactivate |
| Activate tenant | PATCH /api/v1/platform-admin/tenants/{id}/activate |
| Delete tenant (legacy alias for deactivate) | DELETE /api/v1/platform-admin/tenants/{id} |
| Create platform user | POST /api/v1/platform-admin/users |
| List platform users | GET /api/v1/platform-admin/users |
| Update platform user | PUT /api/v1/platform-admin/users/{id} |
| Delete platform user | DELETE /api/v1/platform-admin/users/{id} |
| Issue platform API key | POST /api/v1/platform-admin/api-keys |
| List platform API keys | GET /api/v1/platform-admin/api-keys |
| Revoke platform API key | DELETE /api/v1/platform-admin/api-keys/{keyId} |
Was this page helpful?