Inviting Users

Overview

The user invitation system enables administrators to onboard new team members to the ASCEND platform. When you invite a user, the system creates both database and identity provider (Cognito) records, then sends a welcome email with login credentials. This ensures a secure, streamlined onboarding experience.

Prerequisites

• org_admin, Admin, or Super_Admin role
• Available user seats in your subscription
• Valid email address for the new user
• Understanding of which role to assign

Step-by-Step Guide

Inviting a Single User

1. Open the Invite Modal

   • Navigate to Admin Console
   • Select the "Users" tab
   • Click "+ Invite User" button in the header

2. Enter User Information

   • Email Address (required): The user's corporate email
   • First Name (required): User's given name
   • Last Name (required): User's family name

3. Select Role

   • Choose from the role dropdown:
     • Viewer: Read-only dashboard access
     • Analyst: Create rules and view alerts
     • Admin: Full access except billing
     • Organization Admin: Full administrative access

4. Send Invitation

   • Click "Send Invitation" button
   • Wait for confirmation toast
   • User appears in table with "Pending" status

What Happens After Invitation

1. System Creates Records

   • Database user record with organization link
   • Cognito user with custom attributes
   • Audit log entry for compliance

2. Email Delivery

   • Welcome email sent to user
   • Contains:
     • Login URL with organization slug
     • Temporary password
     • MFA setup instructions (if required)
     • Link to documentation

3. User First Login

   • User navigates to login URL
   • Enters email and temporary password
   • Prompted to set new password
   • Completes MFA setup (if required)
   • Status changes to "Active"

Configuration Options

Option	Description	Default
Role	Access level for the new user	analyst
is_org_admin	Grant organization admin privileges	false
access_level	RBAC level (0-5)	1

Invitation Requirements

Email Validation

• Must be a valid email format
• Cannot already exist in your organization
• Domain restrictions may apply (enterprise feature)

Name Requirements

• First name: 1-100 characters
• Last name: 1-100 characters
• Unicode characters supported

Role Restrictions

• Only admins can create other admins
• org_admin flag requires admin role
• Access level must not exceed inviter's level

User Limits by Tier

Tier	Included Users	Notes
Pilot	Unlimited	Trial period only
Professional	Unlimited	No per-seat fees
Business	Unlimited	No per-seat fees
Enterprise	Unlimited	No per-seat fees

All ASCEND tiers include unlimited users. You are billed based on AI agent actions, not user seats.

Invitation Email Template

The system sends an email containing:

Subject: You've been invited to ASCEND - [Organization Name]

Hi [First Name],

You've been invited to join [Organization Name] on ASCEND,
the AI Governance Platform.

Your Login Details:
-------------------
Login URL: https://[org-slug].ascend.ai/login
Email: [user-email]
Temporary Password: [generated-password]

Your Role: [assigned-role]

Getting Started:
1. Click the login URL above
2. Enter your email and temporary password
3. Set your new password
4. Configure MFA (if required)
5. Explore your dashboard

Need Help?
- Documentation: https://docs.ascend.ai
- Support: support@ascend.ai

Welcome to ASCEND!

---
Invited by: [admin-email]
[Organization Name]

API Reference

Invite User Endpoint

POST /api/admin/users/invite
Authorization: Bearer <token>
X-CSRF-Token: <csrf_token>
Content-Type: application/json

Request Body:

{
  "email": "john.doe@company.com",
  "first_name": "John",
  "last_name": "Doe",
  "role": "analyst",
  "is_org_admin": false,
  "access_level": 2
}

Success Response:

{
  "success": true,
  "message": "Invitation sent to john.doe@company.com",
  "user_id": 123,
  "cognito_user_id": "abc123-def456",
  "cognito_enabled": true
}

Error Responses:

Status	Code	Description
400	Invalid role	Role not in allowed list
403	User limit reached	Upgrade subscription
403	Cannot create admin	Insufficient privileges
409	Email exists	User already in organization
500	Cognito error	Identity provider issue

Troubleshooting

Invitation Not Received

Cause	Solution
Email in spam	Check spam/junk folder
Invalid email	Verify email address spelling
Domain blocking	Check corporate email filters
SES sandbox	Verify sender in AWS SES

User Cannot Login

Issue	Solution
Wrong password	Use exact temporary password from email
Password expired	Re-send invitation
Account locked	Wait 15 minutes or contact admin
MFA failure	Verify authenticator time sync

Invitation Failed

Error	Solution
User limit reached	Upgrade subscription tier
Email already exists	Check for existing user, reactivate if needed
Cognito error	Check AWS service status
Rate limited	Wait 1 minute before retrying

Best Practices

1. Verify Email Addresses

   • Confirm correct spelling before inviting
   • Use corporate email addresses only
   • Avoid personal email addresses for compliance

2. Choose Appropriate Roles

   • Start with lowest necessary privilege
   • Document role assignment rationale
   • Review and adjust after onboarding

3. Time Invitations Appropriately

   • Send invitations 1-2 days before needed access
   • Coordinate with user's schedule
   • Ensure someone is available to assist

4. Follow Up on Pending Users

   • Check for pending invitations weekly
   • Re-send if invitation expired
   • Remove if user no longer needs access

5. Bulk Onboarding

   • For large teams, invite in batches
   • Stagger invitations to avoid email delays
   • Consider group training sessions

Compliance Considerations

Audit Trail

Every invitation creates an audit log entry containing:

• Inviter's user ID and email
• Invitee's email and assigned role
• Timestamp and IP address
• Cognito user ID (if created)

Access Control

• Invitations require CSRF token validation
• Rate limited to 10 invitations per minute
• Role elevation requires matching or higher privilege
• All operations logged for SOC 2 compliance

Data Protection

• Temporary passwords are cryptographically random
• Passwords hashed with bcrypt before storage
• Email contains no sensitive organization data
• Invitation links expire after 7 days

Related

• User Management Overview - Full user lifecycle
• Role Assignment - Understanding roles
• Admin Console - Console navigation