Organization Invitations

Organization invitations enable you to onboard new members to your organization with pre-configured roles, permissions, and site access. The invitation system supports both authenticated (admin) and public (invitee) workflows.

Overview

The invitation system provides a secure way to:

Invite new users to join your organization via email
Pre-configure user roles and permissions before acceptance
Grant access to specific sites with custom permissions
Track invitation status and manage pending invitations
Allow invitees to accept invitations without prior authentication

Key Features

Flexible Permission Setup

Assign users to groups automatically upon acceptance
Grant site-specific permissions
Configure access levels before the user joins

Secure Public Access

Invitees can view and accept invitations without authentication
Unique, secure invitation tokens prevent unauthorized access
One-time use tokens prevent duplicate acceptances

Email Integration

Automatic invitation emails with acceptance links
Customizable email templates
Resend functionality for expired or lost invitations

For Organization Admins

Creating Invitations

Send an invitation to a new member with optional group and site access configuration.

Endpoint:

POST /api/cloud/organizations/{org_slug}/invitations/

Authentication: Required (Bearer token)

Request Body:

{
  "invitee_identifier": "user@example.com",
  "invitation_config": {
    "group": [3, 5],
    "site": [
      {
        "slug": "my-site",
        "permissions": ["view_site", "manage_site"]
      },
      {
        "slug": "another-site",
        "permissions": ["view_site"]
      }
    ]
  }
}

Parameters:

invitee_identifier (required): Email address of the person to invite
invitation_config (optional): Configuration for member setup
- group: Array of group IDs to assign the user to
- site: Array of site configurations with slug and permissions

Example:

curl -X POST "https://api.taruvi.cloud/api/cloud/organizations/acme-corp/invitations/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invitee_identifier": "newuser@acme.com",
    "invitation_config": {
      "group": [3],
      "site": [
        {
          "slug": "production-site",
          "permissions": ["view_site", "manage_site"]
        }
      ]
    }
  }'

Response: 201 Created

{
  "id": 1,
  "uuid": "6cd09cc9-1724-4371-8c6f-336eba61e46e",
  "organization": 1,
  "organization_name": "Acme Corporation",
  "invitee_identifier": "newuser@acme.com",
  "invited_by": 1,
  "invited_by_user": {
    "id": 1,
    "uuid": "1b3c4d93-e058-457f-85b8-0276dd4af5c4",
    "username": "admin",
    "email": "admin@acme.com",
    "first_name": "Admin",
    "last_name": "User"
  },
  "invitee": null,
  "invitee_user": null,
  "config": {
    "group": [3],
    "site": [
      {
        "slug": "production-site",
        "permissions": ["view_site", "manage_site"]
      }
    ]
  },
  "created": "2025-11-18T10:00:00Z"
}

Automatic Email

An invitation email is automatically sent to the invitee with a secure acceptance link.

Listing Invitations

View all pending invitations for your organization.

Endpoint:

GET /api/cloud/organizations/{org_slug}/invitations/

Authentication: Required (Bearer token)

Query Parameters:

search: Search by invitee email
ordering: Sort by created, -created

Example:

curl -X GET "https://api.taruvi.cloud/api/cloud/organizations/acme-corp/invitations/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response: 200 OK

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "uuid": "6cd09cc9-1724-4371-8c6f-336eba61e46e",
      "organization": 1,
      "organization_name": "Acme Corporation",
      "invitee_identifier": "newuser@acme.com",
      "invited_by": 1,
      "config": {
        "group": [3],
        "site": [...]
      },
      "created": "2025-11-18T10:00:00Z"
    }
  ]
}

Resending Invitations

Resend the invitation email if the original was lost or expired.

Endpoint:

POST /api/cloud/organizations/{org_slug}/invitations/{uuid}/resend/

Authentication: Required (Bearer token)

Example:

curl -X POST "https://api.taruvi.cloud/api/cloud/organizations/acme-corp/invitations/6cd09cc9-1724-4371-8c6f-336eba61e46e/resend/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response: 200 OK

{
  "message": "Invitation resent successfully"
}

Deleting Invitations

Cancel a pending invitation.

Endpoint:

DELETE /api/cloud/organizations/{org_slug}/invitations/{uuid}/

Authentication: Required (Bearer token)

Example:

curl -X DELETE "https://api.taruvi.cloud/api/cloud/organizations/acme-corp/invitations/6cd09cc9-1724-4371-8c6f-336eba61e46e/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response: 204 No Content

For Invitees (Public Access)

Viewing Invitation Details

View invitation details before accepting (no authentication required).

Endpoint:

GET /api/cloud/invitations/{token}/details/

Authentication: None (Public endpoint)

Example:

curl -X GET "https://api.taruvi.cloud/api/cloud/invitations/6cd09cc9-1724-4371-8c6f-336eba61e46e/details/"

Response: 200 OK

{
  "id": 1,
  "uuid": "6cd09cc9-1724-4371-8c6f-336eba61e46e",
  "organization": 1,
  "organization_name": "Acme Corporation",
  "invitee_identifier": "newuser@acme.com",
  "invited_by": 1,
  "invited_by_user": {
    "id": 1,
    "username": "admin",
    "email": "admin@acme.com",
    "first_name": "Admin",
    "last_name": "User"
  },
  "config": {
    "group": [3],
    "site": [...]
  },
  "created": "2025-11-18T10:00:00Z"
}

Error Responses:

404 Not Found: Invalid invitation token
410 Gone: Invitation already accepted

Accepting Invitations

Accept an invitation and create/activate your user account (no authentication required).

Endpoint:

POST /api/cloud/invitations/{token}/accept/

Authentication: None (Public endpoint)

Request Body:

{
  "password": "SecurePassword123!",
  "first_name": "John",
  "last_name": "Doe"
}

Parameters:

password (required): Password for your new account
first_name (required): Your first name
last_name (required): Your last name

Example:

curl -X POST "https://api.taruvi.cloud/api/cloud/invitations/6cd09cc9-1724-4371-8c6f-336eba61e46e/accept/" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePassword123!",
    "first_name": "John",
    "last_name": "Doe"
  }'

Response: 200 OK

{
  "success": true,
  "message": "Invitation accepted successfully",
  "user": {
    "id": 5,
    "email": "newuser@acme.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "organization": {
    "id": 1,
    "slug": "acme-corp",
    "name": "Acme Corporation"
  }
}

What Happens:

✅ User account is created (or activated if it exists)
✅ Password is set for the account
✅ User is added to the organization
✅ Groups are assigned automatically
✅ Site permissions are granted
✅ Invitation is marked as used (cannot be accepted again)

Error Responses:

400 Bad Request: Missing or invalid password/name
404 Not Found: Invalid invitation token
410 Gone: Invitation already accepted

After accepting an invitation, you can immediately log in using the email and password you provided.

Invitation Workflow

Standard Flow

sequenceDiagram
    participant Admin
    participant API
    participant Email
    participant Invitee

    Admin->>API: POST /organizations/{slug}/invitations/
    API->>API: Create invitation with config
    API->>Email: Send invitation email
    API->>Admin: Return invitation details

    Email->>Invitee: Deliver invitation email
    Invitee->>API: GET /invitations/{token}/details/
    API->>Invitee: Show organization details

    Invitee->>API: POST /invitations/{token}/accept/
    API->>API: Create/activate user
    API->>API: Apply groups & permissions
    API->>Invitee: Return success with user details

Step-by-Step

Admin creates invitation
- Specifies invitee email
- Configures groups and site permissions
- Receives invitation UUID
System processes invitation
- Creates placeholder user (inactive)
- Stores configuration
- Sends invitation email
Invitee receives email
- Gets unique invitation link
- Link contains secure token
Invitee views details (optional)
- Sees organization name
- Sees who invited them
- Reviews access they'll receive
Invitee accepts invitation
- Provides password and name
- Account is activated
- Groups and permissions applied automatically
Invitee can log in
- Uses email and password
- Has immediate access to organization and sites

Permission Configuration

Group Assignment

Groups define broad role-based access. Common group examples:

Admin: Full organization management
Member: Standard user access
Viewer: Read-only access
Developer: Site management access

Example:

{
  "invitation_config": {
    "group": [3, 5]
  }
}

Group IDs

Group IDs can be obtained from the Groups API. Contact your organization admin for available groups.

Site Permissions

Grant granular access to specific sites within the organization.

Available Permissions:

access_site: Basic access to the site
view_site: Read-only access to the site
change_site: Modify site settings
delete_site: Delete the site
manage_site: Full site management
manage_site_users: Manage site user permissions
admin_site: Full site administration

Example:

{
  "invitation_config": {
    "site": [
      {
        "slug": "production-site",
        "permissions": ["view_site", "manage_site"]
      },
      {
        "slug": "staging-site",
        "permissions": ["view_site"]
      }
    ]
  }
}

Site Slugs

Site slugs must exist in the organization before the invitation is accepted. Invalid slugs are silently ignored.

Best Practices

For Admins

Minimal Permissions: Only grant necessary permissions
Group Strategy: Use groups for consistent role assignment
Regular Cleanup: Delete or resend expired invitations
Monitor Acceptance: Track which invitations are pending
Audit Access: Review member permissions after acceptance

For Invitees

Strong Passwords: Use secure passwords (min 8 characters, mixed case, numbers)
Verify Organization: Check invitation details before accepting
Contact Support: If invitation seems suspicious, verify with sender
Save Credentials: Store your email and password securely

Security Features

Token-Based Access

Invitations use UUID v4 tokens (128-bit randomness)
Tokens are single-use and expire after acceptance
No authentication required for acceptance (secure by obscurity)

Rate Limiting

API endpoints are rate-limited to prevent abuse
Failed attempts are logged and monitored

Email Verification

Invitations are sent to the specified email address
Only the recipient can access the invitation link

Audit Trail

All invitation actions are logged
Track who invited whom and when
Monitor acceptance patterns

Common Use Cases

Onboarding Team Members

Invite new employees with pre-configured access to relevant sites and tools.

{
  "invitee_identifier": "newemployee@company.com",
  "invitation_config": {
    "group": [3],  // Developer group
    "site": [
      {
        "slug": "dev-environment",
        "permissions": ["view_site", "manage_site"]
      }
    ]
  }
}

External Collaborators

Grant limited access to specific sites for contractors or partners.

{
  "invitee_identifier": "contractor@external.com",
  "invitation_config": {
    "group": [7],  // Guest group
    "site": [
      {
        "slug": "client-site",
        "permissions": ["view_site"]
      }
    ]
  }
}

Multi-Site Access

Provide different permission levels across multiple sites.

{
  "invitee_identifier": "manager@company.com",
  "invitation_config": {
    "group": [2],  // Manager group
    "site": [
      {
        "slug": "site-a",
        "permissions": ["manage_site"]
      },
      {
        "slug": "site-b",
        "permissions": ["view_site"]
      }
    ]
  }
}

Troubleshooting

Invitation Not Received

Check spam/junk folders
Verify email address is correct
Use resend functionality
Check organization email settings

Cannot Accept Invitation

Ensure invitation hasn't been accepted already (check for 410 error)
Verify invitation token in URL is complete
Check password meets requirements
Try a different browser

Wrong Permissions After Acceptance

Verify invitation config was correct
Check group membership in organization settings
Contact organization admin to adjust permissions
Review site-specific permissions

Email Already Exists

If the email is already registered:

The existing account will be activated
New password will override the old one
User will be added to the new organization
Previous organization memberships are retained

API Reference Summary

Endpoint	Method	Auth	Purpose
`/organizations/{slug}/invitations/`	POST	Required	Create invitation
`/organizations/{slug}/invitations/`	GET	Required	List invitations
`/organizations/{slug}/invitations/{uuid}/`	GET	Required	Get invitation details
`/organizations/{slug}/invitations/{uuid}/`	DELETE	Required	Cancel invitation
`/organizations/{slug}/invitations/{uuid}/resend/`	POST	Required	Resend invitation email
`/invitations/{token}/details/`	GET	Public	View invitation (invitee)
`/invitations/{token}/accept/`	POST	Public	Accept invitation (invitee)

Organizations - Learn about organization management
Users - User account management
Groups - Role-based access control
Permissions - Fine-grained permission system
Sites - Multi-tenant site management

Overview​

Key Features​

Flexible Permission Setup​

Secure Public Access​

Email Integration​

For Organization Admins​

Creating Invitations​

Listing Invitations​

Resending Invitations​

Deleting Invitations​

For Invitees (Public Access)​

Viewing Invitation Details​

Accepting Invitations​

Invitation Workflow​

Standard Flow​

Step-by-Step​

Permission Configuration​

Group Assignment​

Site Permissions​

Best Practices​

For Admins​

For Invitees​

Security Features​

Token-Based Access​

Rate Limiting​

Email Verification​

Audit Trail​

Common Use Cases​

Onboarding Team Members​

External Collaborators​

Multi-Site Access​

Troubleshooting​

Invitation Not Received​

Cannot Accept Invitation​

Wrong Permissions After Acceptance​

Email Already Exists​

API Reference Summary​

Related Documentation​

Overview

Key Features

Flexible Permission Setup

Secure Public Access

Email Integration

For Organization Admins

Creating Invitations

Listing Invitations

Resending Invitations

Deleting Invitations

For Invitees (Public Access)

Viewing Invitation Details

Accepting Invitations

Invitation Workflow

Standard Flow

Step-by-Step

Permission Configuration

Group Assignment

Site Permissions

Best Practices

For Admins

For Invitees

Security Features

Token-Based Access

Rate Limiting

Email Verification

Audit Trail

Common Use Cases

Onboarding Team Members

External Collaborators

Multi-Site Access

Troubleshooting

Invitation Not Received

Cannot Accept Invitation

Wrong Permissions After Acceptance

Email Already Exists

API Reference Summary

Related Documentation