User Mutations

The User API provides mutations to manage users in your board.

Create User

Create a new user.

Mutation Structure

mutation CreateUser(
  $ssoId: String!
  $name: String!
  $email: String!
  $emailOnMention: Boolean
  $bio: String
  $imageUrl: String
  $ssoType: SSOTypes!
  $isApiUser: Boolean
) {
  createUser(
    ssoId: $ssoId
    name: $name
    email: $email
    emailOnMention: $emailOnMention
    bio: $bio
    imageUrl: $imageUrl
    ssoType: $ssoType
    isApiUser: $isApiUser
  ) {
    bio
    email
    emailOnMention
    image
    isSsoUser
    isAPIUser
    name
    ssoId
    ssoType
  }
}

Input Fields

Field	Type	Description
ssoId	String!	External SSO identifier for the user
name	String!	User's name
email	String!	User's email address
emailOnMention	Boolean	Whether to send email notifications on mentions (default: true)
bio	String	User's biography
imageUrl	String	URL of the user's profile image
ssoType	SSOTypes!	Type of SSO authentication
isApiUser	Boolean	Whether the user is created through the API (default: false)

Return Type

Returns the created User object with the fields specified in the query.

Update User

Update an existing user.

Mutation Structure

mutation UpdateUser(
  $ssoId: String!
  $name: String
  $email: String
  $emailOnMention: Boolean
  $bio: String
  $imageUrl: String
) {
  updateUser(
    ssoId: $ssoId
    name: $name
    email: $email
    emailOnMention: $emailOnMention
    bio: $bio
    imageUrl: $imageUrl
  ) {
    bio
    email
    emailOnMention
    image
    isSsoUser
    isAPIUser
    name
    ssoId
    ssoType
  }
}

Input Fields

Field	Type	Description
ssoId	String!	SSO identifier of the user to update
name	String	New name for the user
email	String	New email address for the user
emailOnMention	Boolean	Whether to send email notifications on mentions
bio	String	New biography for the user
imageUrl	String	New profile image URL for the user

Return Type

Returns the updated User object with the fields specified in the query.

Delete User

Delete an existing user.

Mutation Structure

mutation DeleteUser($ssoId: String!) {
  deleteUser(ssoId: $ssoId) {
    bio
    email
    name
    ssoId
    ssoType
  }
}

Input Fields

Field	Type	Description
ssoId	String!	SSO identifier of the user to delete

Return Type

Returns the deleted User object with the fields specified in the query.

SSOTypes Enum

Value	Description
SSO	Generic SSO authentication
SSO_SAML	SAML-based SSO authentication
SSO_OIDC	OpenID Connect-based SSO authentication

Error Handling

The User mutations require proper authentication and write access. They will return appropriate error messages if:

• The API key is invalid
• Write access is not granted
• The SSO type header is missing
• Required fields are missing or invalid
• The user does not exist (for update/delete)

Common error scenarios:

{
  "errors": [
    {
      "message": "Invalid Api Key",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Write access required",
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "ssotype is required in headers",
      "extensions": {
        "code": "BAD_REQUEST"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "User not found",
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

Notes

1. When a user is deleted:

   • Their files are deleted
   • Their invitations are removed
   • Their login tokens are invalidated
   • Their board memberships are removed
   • Their subscriptions are canceled
   • Their name is changed to "Deleted User"
   • Their email is anonymized

2. The API requires the ssotype header to be set for all operations to identify the SSO provider being used.

3. Write access is required for all mutation operations. Make sure your API key has the necessary permissions.