Platform & Partners

Invite Flow

How super admins invite platform admins, and how platform admins invite tenant users — both use a signed, one-time email token.

Super admin → Platform admin

A super admin visits /admin/tenants, selects a partner platform tenant, and clicks Invite Platform Admin. This fires:

bash

POST https://devapi.teamcast.ai/api/v2/platform/tenants/:tenantId/invite
Authorization: Bearer <super_admin_token>

{
  "email": "admin@partner.example.com",
  "role": "platform_admin"
}

tc-core mints a JWT signed with JWT_SECRET, stores a one-time-use record, and sends an invitation email. The token expires in 24 hours and carries: tenantId, email, invitedBy, and role.

1.Super admin sends invite

2.tc-core mints signed JWT (24h, one-time-use)

3.Email sent → "Accept your Teamcast invitation"

4.Invited user clicks link → /accept-invite?token=<jwt>

5.Page validates token, shows set-password form

6.POST /auth/accept-invite → activates account

7.Redirect to /admin (Platform Console)

The accept-invite token is single-use and is consumed on submission. If the link is clicked a second time, the user receives an invalid_token error. The super admin must send a new invite.

Platform admin permissions granted on acceptance

When the invite is accepted, the new platform admin's account is seeded with this curated set of permissions (from seed 0004_platform_admin_permissions.sql):

Permission key	What it unlocks
platform:tenants:read	List and view customer tenants under the platform
platform:tenants:manage	Create, update, suspend customer tenants; provision integrations for them
platform:billing:read	View billing info for the platform
platform:settings:read	View platform-level settings
platform:settings:manage	Update platform-level settings
platform:oauth_clients:read	View OAuth clients registered for the platform
platform:oauth_clients:manage	Create and manage OAuth clients for the platform
platform:users:manage	Manage users within the platform
platform:interviews:rescore	Trigger re-assessment on completed interviews
platform:impersonate	Impersonate any user within the platform
apikey:read	List API keys for any tenant under the platform
apikey:create	Create API keys for any tenant under the platform
apikey:delete	Revoke API keys for any tenant under the platform
webhook:read	Read webhook config for any tenant under the platform
webhook:update	Write webhook config for any tenant under the platform

Platform admins do not receive the wildcard * permission. They can only target tenants whose parentPlatformId matches their own tenant — enforced server-side on every admin endpoint.

Platform admin → Tenant user invite

Platform admins can invite workspace users into customer tenants under their platform. The invite endpoint is the same but scoped to a customer tenantId:

bash

POST https://devapi.teamcast.ai/api/v2/platform/tenants/:customerTenantId/invite
Authorization: Bearer <platform_admin_token>

{
  "email": "recruiter@customer.example.com",
  "role": "tenant_user"
}

The invited user follows the same accept-invite flow but lands on /recruiter (the workspace console) after password setup, because their roleDiscriminator is tenant_user.

Accept-invite page

The accept-invite UI lives at /accept-invite?token=<jwt>. It:

Decodes the token client-side to show the target email address and tenant name.
Presents a set-password form (password + confirm).
Submits POST /auth/accept-invite with the token and new password.
On success, redirects to /admin (platform admin) or /recruiter (tenant user) based on the role in the token.

Token decoding is display-only — the actual role and tenantId are read from the server on submission. The client cannot elevate the role by modifying the page.

Was this page helpful?

Previous← Overview

NextIntegration management →