Invite User

Use the inviteUser mutation to add a person to a workspace or organization by email. If the email already belongs to a registered Blue user who is part of the organization, they are added to the workspace immediately. Otherwise Blue sends them an invitation email; they join once they accept. Workspaces are Workspace objects and organizations are Organization objects in the API.

inviteUser returns a bare Boolean! — there is no object to select fields from. A successful call resolves to true.

Request

Send the request to https://api.blue.app/graphql with your authentication headers. The blue-workspace-id header (workspace ID or slug) is required for workspace-scoped invites.

POST https://api.blue.app/graphql
blue-token-id: YOUR_TOKEN_ID
blue-token-secret: YOUR_TOKEN_SECRET
blue-org-id: YOUR_ORG_ID
blue-workspace-id: project_123

Invite one person to a single workspace as a member:

mutation InviteUser {
  inviteUser(
    input: { email: "teammate@example.com", projectId: "project_123", accessLevel: MEMBER }
  )
}

You must supply either projectId or companyId. Supplying neither throws BAD_USER_INPUT.

Parameters

InviteUserInput

At least one of projectId or companyId is required.

UserAccessLevel

Response

{
  "data": {
    "inviteUser": true
  }
}

true means the invitation was created (or an existing pending invitation was re-sent), or — for an already-registered organization member — that they were added to the workspace directly.

Workspace invites

Pass projectId to invite into a single workspace. The caller must have invite permission in that workspace (VIEW_ONLY and COMMENT_ONLY members cannot invite), and the access level they assign is capped by their own role — see Permissions.

If the invitee is already a registered Blue user who belongs to the workspace’s organization, they are added to the workspace right away with the requested access level. If they are an organization OWNER, they are granted ADMIN in that workspace regardless of the accessLevel you request. Everyone else receives an invitation email and joins on acceptance.

Organization invites

Pass companyId to invite into an organization. Only an organization OWNER can do this — otherwise the call throws FORBIDDEN. Use projectIds to list the workspaces the invitee should be added to:

mutation InviteUserToOrganization {
  inviteUser(
    input: {
      email: "contractor@example.com"
      companyId: "company_123"
      projectIds: ["project_123", "project_456"]
      accessLevel: MEMBER
    }
  )
}

Each listed workspace produces its own invitation, consolidated into a single email. Omitting projectIds adds the invitee to zero workspaces — a brand-new invitee gains no membership until they are invited into at least one workspace, so include the workspaces you want them in.

Custom roles

To assign a custom role instead of a built-in access level, set accessLevel: MEMBER and pass the role’s roleId. The role must belong to the target workspace, and the invitee inherits the permissions defined on it. Retrieve available roles with the workspaceUserRoles query.

mutation InviteUserWithRole {
  inviteUser(
    input: {
      email: "contractor@example.com"
      projectId: "project_123"
      accessLevel: MEMBER
      roleId: "role_123"
    }
  )
}

Re-inviting

Calling inviteUser again for an email that already has a pending invitation does not error. Blue reuses the existing invitation and re-sends it, so links in earlier emails stay valid. Invitations expire 7 days after they are sent.

Errors

A seat-limit error includes the limit context in extensions:

{
  "errors": [
    {
      "message": "Users limit reached (5/5). Upgrade your plan for more.",
      "extensions": {
        "code": "PLAN_LIMIT_REACHED",
        "kind": "over_limit",
        "resource": "Users",
        "current": 5,
        "limit": 5
      }
    }
  ]
}

Permissions

For workspace invites, the access level you can assign is capped by your own role in that workspace:

Only a workspace OWNER may assign OWNER. Organization invites (companyId) require the caller to be an organization OWNER.

Related

• List users — see who already has access.
• Remove users — revoke workspace or organization access.
• Custom roles — list the roles you can pass as roleId.

Manage the invitation that an invite produces with the resendInvitation and cancelInvitation mutations.