Invite User

Invite a User

The inviteUser mutation allows you to invite users to your Blue projects or companies. Users can be assigned predefined access levels or custom roles with specific permissions.

Basic Example

Invite a user with a standard access level:

mutation InviteUserToProject {
  inviteUser(
    input: {
      email: "[email protected]"
      projectId: "web-redesign"
      accessLevel: MEMBER
    }
  )
}

Advanced Example

Invite a user with a custom role to multiple projects:

mutation InviteUserWithCustomRole {
  inviteUser(
    input: {
      email: "[email protected]"
      projectIds: ["web-redesign", "mobile-app", "api-v2"]
      accessLevel: MEMBER
      roleId: "role_contractor_123"
    }
  )
}

Input Parameters

InviteUserInput

UserAccessLevel Values

Response Fields

Required Permissions

Users must have sufficient permissions to invite others. The permission hierarchy is enforced:

Note: For company invitations (using companyId), only company OWNERS can invite users.

Invitation Types

Project Invitation

Invite a user to a single project:

• Use projectId parameter
• Cannot use companyId simultaneously
• Inviter must have access to the project
• Access level restrictions apply

Company Invitation

Invite a user to a company (and optionally specific projects):

• Use companyId parameter
• Cannot use projectId simultaneously
• Only company OWNERS can use this method
• Use projectIds array to specify which projects to include
• If projectIds is omitted, user gets company access only

Custom Roles

When using custom roles:

1. Set accessLevel to MEMBER
2. Provide the roleId of your custom role
3. The user will inherit all permissions defined in the custom role
4. Custom roles are project-specific

To retrieve available custom roles, use the projectUserRoles query.

Error Responses

User Already in Project

{
  "errors": [{
    "message": "User is already in the project.",
    "extensions": {
      "code": "USER_ALREADY_IN_THE_PROJECT"
    }
  }]
}

Insufficient Permissions

{
  "errors": [{
    "message": "You don't have permission to invite users with this access level",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

Invalid Project

{
  "errors": [{
    "message": "Project not found",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Invitation Limit Exceeded

{
  "errors": [{
    "message": "Unable to invite more people.",
    "extensions": {
      "code": "INVITATION_LIMIT"
    }
  }]
}

Cannot Invite Yourself

{
  "errors": [{
    "message": "You are not allowed to add yourself.",
    "extensions": {
      "code": "ADD_SELF"
    }
  }]
}

Invalid Custom Role

{
  "errors": [{
    "message": "Project user role was not found.",
    "extensions": {
      "code": "PROJECT_USER_ROLE_NOT_FOUND"
    }
  }]
}

Company Banned

{
  "errors": [{
    "message": "Company is banned",
    "extensions": {
      "code": "COMPANY_BANNED"
    }
  }]
}

Important Notes

• Email Validation: Email addresses are normalized and validated before sending invitations
• Invitation Expiry: Invitations expire after 7 days and must be resent if not accepted
• Automatic Notifications: Blue automatically sends invitation emails to new users
• Company Owners: Company owners automatically receive ADMIN access in all projects
• Activity Logging: All user invitations are logged for audit purposes
• Parameter Exclusivity: You must provide either projectId OR companyId, not both
• Company Restrictions: Only company owners can use the companyId parameter
• Self-Invitation: Users cannot invite themselves (will throw ADD_SELF error)

Related Operations

• List Users - View all users in a project or company
• Remove User - Remove users from projects
• Custom Roles - Manage custom user roles