Inviting Users

What is User Invitation?

The invite users endpoint allows administrators to add new users to the CampusMindAI platform. The system first verifies the user exists in your organization's Microsoft Entra ID (Azure AD) before adding them to the CampusMindAI database with a specified role.

Why Use User Invitation?

• Controlled Onboarding: Ensure only authorized users can access the platform

• Role Assignment: Assign appropriate permissions during invitation

• Azure AD Verification: Automatically validates users against your organization's directory

• Audit Trail: Track who invited each user to the system

Prerequisites

• Administrator or appropriate role permissions

• Valid JWT authentication token

• User must exist in your organization's Azure AD tenant

• Azure AD token from the authentication script

User Roles

CampusMindAI supports three primary user roles:

Invite Users Endpoint

Endpoint Details

• Method: POST

• URL: {{baseURL}}/api/v1/invite_users/

• Authentication: Required (JWT Bearer token)

Request Headers

Authorization: Bearer <jwt-token>
Content-Type: application/json

Request Body

Example Request

curl -X POST "https://<baseURL>/api/v1/invite_users/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "newuser@example.com",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "user_role": 2
  }'

Successful Response

Status Code: 200 OK

{
  "message": "Invitation sent successfully.",
  "status": "pending"
}

Error Responses

How It Works

Verification Process

1. Azure AD Lookup: The system queries Microsoft Graph API using the provided Azure AD token

2. User Validation: Confirms the email address exists in your organization's directory

3. Database Registration: If verified, adds the user to CampusMindAI with the specified role

4. Invitation Status: Returns confirmation of the invitation

Azure AD Token Requirement

The access_token parameter must be the Azure AD token generated by the ROPC authentication script, not the CampusMindAI JWT token. This token allows the system to verify users against your Azure AD tenant.

Usage Examples

Inviting a Student

{
  "email_address": "student@university.edu",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "user_role": 1
}

Inviting an Instructor

{
  "email_address": "professor@university.edu",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "user_role": 2
}

Inviting an Administrator

{
  "email_address": "admin@university.edu",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "user_role": 3
}

Invitation Workflow

Step 1: Obtain Azure AD Token

Run the authentication script to get your Azure AD token:

python azure_login.py

Copy the output token.

Step 2: Authenticate with CampusMindAI

Exchange the Azure AD token for a JWT token:

curl -X GET "https://<baseURL>/api/v1/login" \
  -H "Authorization: Bearer <azure-ad-token>"

Step 3: Invite the User

Use both tokens to invite the user:

curl -X POST "https://<baseURL>/api/v1/invite_users/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "newuser@example.com",
    "access_token": "<azure-ad-token>",
    "user_role": 2
  }'

Best Practices

Email Validation

• Always use the user's organizational email address

• Verify the email domain matches your Azure AD tenant

• Check for typos before sending invitations

Role Assignment

• Start with lower privileges: Assign Student or Instructor roles initially

• Promote as needed: Upgrade roles after users demonstrate need

• Regular audits: Review user roles periodically

Bulk Invitations

For inviting multiple users, implement error handling and logging:

users_to_invite = [
    {"email": "user1@example.com", "role": 1},
    {"email": "user2@example.com", "role": 2},
    {"email": "user3@example.com", "role": 1}
]

for user in users_to_invite:
    try:
        response = invite_user(user["email"], user["role"])
        print(f"✓ Invited {user['email']}")
    except Exception as e:
        print(f"✗ Failed to invite {user['email']}: {str(e)}")

Troubleshooting

User Not Found in Azure AD

Error: 404 Not Found - User not found

Solutions:

• Verify the email address is correct

• Ensure the user exists in your Azure AD tenant

• Check that the user's account is active

• Confirm you're using the correct tenant

Invalid Access Token

Error: 401 Unauthorized

Solutions:

• Verify you're using the Azure AD token (not JWT) in the access_token field

• Check that the Azure AD token hasn't expired

• Regenerate the token using the authentication script

• Ensure the token has Microsoft Graph API permissions

User Already Exists

If a user has already been invited:

• Check the user list using the List Users endpoint

• User can log in directly without re-invitation

• To change their role, use the appropriate role management endpoint

Permission Denied

Error: 403 Forbidden

Solutions:

• Verify your account has administrator privileges

• Check your user role in CampusMindAI

• Contact your system administrator for permission elevation

Security Considerations

Token Management

• Never expose tokens: Keep Azure AD and JWT tokens secure

• Use HTTPS only: All API calls must use encrypted connections

• Short-lived sessions: Tokens expire for security

Role-Based Access

• Principle of least privilege: Assign minimum required permissions

• Regular reviews: Audit user roles quarterly

• Immediate revocation: Remove access for departing users

Validation Checklist

Before inviting users, verify:

• [ ] User email exists in Azure AD

• [ ] Correct role ID is specified (1, 2, or 3)

• [ ] Azure AD token is current and valid

• [ ] JWT authentication token is included

• [ ] Request format matches documentation

• [ ] You have administrator permissions