API Reference

Invitations

Invite users to join a platform or tenant via email. Invitations include a secure token link for account setup.

The Invitations API allows platform administrators to invite tenant users and super administrators to invite platform users. Each invitation generates a unique token sent via email. The recipient uses the token to set their password and activate their account.

Invitation tokens expire after 7 days. Expired invitations must be re-sent.

Endpoints

Method	Endpoint	Auth	Description
POST	/invitations/tenants/:tenantId	Platform Admin JWT	Invite a user to a tenant
POST	/invitations/platforms/:platformId	Super Admin JWT	Invite a user to a platform
GET	/invitations/:token	Public	Get invitation details by token
POST	/invitations/:token/accept	Public	Accept invitation and set password

POST /invitations/tenants/:tenantId - Invite Tenant User

Send an email invitation to join a specific tenant. The invited user will receive a link to set their password and activate their account with the specified role.

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/invitations/tenants/<tenant-id> \
  -H "Authorization: Bearer <platform-admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "recruiter@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "recruiter"
  }'

Field	Type	Required	Description
email	string	Yes	Email address of the invited user
firstName	string	No	First name (pre-filled on acceptance)
lastName	string	No	Last name (pre-filled on acceptance)
role	string	No	Role to assign: admin, recruiter, or user (default: user)

json

{
  "id": "uuid",
  "email": "recruiter@example.com",
  "status": "pending",
  "expiresAt": "2024-01-08T00:00:00.000Z",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

POST /invitations/platforms/:platformId - Invite Platform User

Send an email invitation for a platform administrator role. Only super administrators can create platform-level invitations.

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/invitations/platforms/<platform-id> \
  -H "Authorization: Bearer <super-admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@partner.com",
    "firstName": "Platform",
    "lastName": "Admin",
    "role": "admin"
  }'

GET /invitations/:token - Get Invitation Details

Retrieve invitation details using the token from the email link. This endpoint is public and used by the acceptance page to display the invitation context before the user sets their password.

bash

curl https://mayaapi.teamcast.ai/api/v1/invitations/<invitation-token>

json

{
  "id": "uuid",
  "email": "recruiter@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "status": "pending",
  "targetType": "tenant",
  "targetName": "Acme Corp",
  "role": "recruiter",
  "expiresAt": "2024-01-08T00:00:00.000Z"
}

Returns 404 if the token is invalid or the invitation has already been accepted. Returns 410 Gone if the invitation has expired.

POST /invitations/:token/accept - Accept Invitation

Accept an invitation and set the account password. This creates the user account and assigns them to the target tenant or platform with the specified role.

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/invitations/<invitation-token>/accept \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePassword123!"
  }'

Field	Type	Required	Description
password	string	Yes	Account password (min 8 characters)

json

{
  "message": "Invitation accepted successfully"
}

Was this page helpful?

Previous← API Keys & OAuth

NextRecording →