Board User Mutations

Add Team User

Add a list of users to the board with specified roles.

Mutation Structure

mutation AddTeamUser($emails: [String!]!, $type: BoardUserType!) {
  addTeamUser(emails: $emails, type: $type) {
    id
    team {
      id
      role
      isInvitationPending
      ssoId
    }
  }
}

Input Fields

Field	Type	Description
emails	[String!]!	List of emails to add to the board
type	BoardUserType!	Role of the users in the board

BoardUserType Enum

Value	Description
ADMIN	Admins can do everything
MEMBER	Members can create posts and comments
MODERATOR	Moderators can moderate posts and comments
OWNER	The Owner is the board creator

Example

mutation {
  addTeamUser(
    emails: ["user@example.com"]
    type: MEMBER
  ) {
    id
    team {
      id
      role
      isInvitationPending
    }
  }
}

Change Team User Role

Change the role of a user in the board.

Mutation Structure

mutation ChangeTeamUserRole($ssoId: String!, $role: BoardUserType!) {
  changeTeamUserRole(ssoId: $ssoId, role: $role) {
    id
    team {
      id
      role
      ssoId
    }
  }
}

Input Fields

Field	Type	Description
ssoId	String!	User's external id
role	BoardUserType!	User's new role in the board

Example

mutation {
  changeTeamUserRole(
    ssoId: "external_user_123"
    role: MODERATOR
  ) {
    id
    team {
      id
      role
      ssoId
    }
  }
}

Remove Team User

Remove a user from the board.

Mutation Structure

mutation RemoveTeamUser($ssoId: String!) {
  removeTeamUser(ssoId: $ssoId)
}

Input Fields

Field	Type	Description
ssoId	String!	User's external id

Example

mutation {
  removeTeamUser(ssoId: "external_user_123")
}

Example Response:

{
  "data": {
    "removeTeamUser": true
  }
}

Authentication

All board user mutations require authentication. You must include your API key and SSO information in the HTTP headers:

{
  "apikey": "YOUR_API_KEY",
  "ssotype": "YOUR_SSO_TYPE"
}

The ssoid header identifies the user making the request. For mutations that modify a specific user (changeTeamUserRole and removeTeamUser), pass the target user's SSO ID in the mutation's ssoId argument.

{
  "apikey": "YOUR_API_KEY",
  "ssotype": "YOUR_SSO_TYPE",
  "ssoid": "EXTERNAL_USER_ID"
}

You can also make requests using curl:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -H "ssotype: YOUR_SSO_TYPE" \
  -H "ssoid: ACTING_USER_SSO_ID" \
  --data '{"query":"mutation AddTeamUser($emails: [String!]!, $type: BoardUserType!) { addTeamUser(emails: $emails, type: $type) { id team { id role isInvitationPending ssoId } } }","variables":{"emails":["user@example.com"],"type":"MEMBER"}}' \
  https://api.nolt.io/api/v1/graphql

Error Handling

The mutations may return errors in the following cases:

• Invalid API key or missing authentication
• Missing SSO type in headers
• Missing SSO ID in headers (for user-specific operations)
• User not found
• Write access required
• Invalid role type

Example error responses:

{
  "errors": [
    {
      "message": "ssotype is required in headers",
      "path": ["changeTeamUserRole"]
    }
  ]
}

{
  "errors": [
    {
      "message": "User not found",
      "path": ["removeTeamUser"]
    }
  ]
}