Users and registration

Everything here is gated on instance admin, except the two public mutations that create an account: registerThroughLink for an invitee, completeSetup for the first account on a fresh install.

Accounts

allUsers

Instance admin only. Returns [GlobalUser!].

Every registered user on the instance (no email).

query {
  allUsers {
    userId
    username
    isInstanceAdmin
    suspended
  }
}

userDetail

Instance admin only. Returns UserDetail.

Full detail (incl. email) for one user.

query {
  userDetail(userId: "user_9f1c2ab7d3e4f5a6") {
    userId
    username
    email
    isInstanceAdmin
    suspended
  }
}

updateUserAdmin

Instance admin only. Returns UserDetail.

Edit a user's instance-admin flag, suspended state, and password.

mutation {
  updateUserAdmin(
    input: { userId: "user_9f1c2ab7d3e4f5a6", isInstanceAdmin: false, suspended: false, canExposePorts: true }
  ) {
    userId
    username
    email
    isInstanceAdmin
    suspended
  }
}

resetUserTwoFactor

Instance admin only. Returns UserDetail.

Clear a user's two-factor enrolment so they can sign in with their password again. The escape hatch for a lost phone AND lost recovery codes; touches no credential and no session.

mutation {
  resetUserTwoFactor(userId: "user_9f1c2ab7d3e4f5a6") {
    userId
    username
    email
    isInstanceAdmin
    suspended
  }
}

resetUserPasskeys

Instance admin only. Returns UserDetail.

Remove every passkey from a user's account. The escape hatch for a lost device: while a dead passkey exists it still satisfies the account's two-factor policy. Touches no password and no session.

mutation {
  resetUserPasskeys(userId: "user_9f1c2ab7d3e4f5a6") {
    userId
    username
    email
    isInstanceAdmin
    suspended
  }
}

deleteUserImpact

Instance admin only. Returns DeleteUserImpact.

What permanently deleting this account would remove. Read-only - nothing is deleted.

query {
  deleteUserImpact(userId: "user_9f1c2ab7d3e4f5a6") {
    username
    tokenCount
    soloTeams {
      name
      appCount
    }
    blockedReason
  }
}

deleteUser

Instance admin only. Returns DeleteUserResult.

Permanently delete a user account. Teams they are the only member of always go with it; the rest is opt-in.

mutation {
  deleteUser(
    input: { userId: "user_9f1c2ab7d3e4f5a6", deleteFoundedTeams: false }
  ) {
    username
    teamsDeleted
    appsDeleted
  }
}

Team access

A person's role in any team, from the instance-admin user editor. allTeamsForAdmin feeds the team picker.

allTeamsForAdmin

Instance admin only. Returns [Team!].

Every team in the instance, for the instance-admin registration-link team picker.

query {
  allTeamsForAdmin {
    id
    slug
    name
    requireTwoFactor
  }
}

addUserToTeam

Instance admin only. Returns [UserTeamAccess!].

Put this person in a team with a role.

mutation {
  addUserToTeam(
    input: { userId: "user_9f1c2ab7d3e4f5a6", teamId: "team_9f1c2ab7d3e4f5a6", roleId: "role_9f1c2ab7d3e4f5a6" }
  ) {
    teamId
    roleName
    granular
  }
}

setUserTeamAccess

Instance admin only. Returns [UserTeamAccess!].

Set one person's role and per-node overrides in one team. Whole-set replace: node grants not sent are removed.

mutation {
  setUserTeamAccess(
    input: { userId: "user_9f1c2ab7d3e4f5a6", teamId: "team_9f1c2ab7d3e4f5a6", roleId: "role_9f1c2ab7d3e4f5a6", granular: false }
  ) {
    teamId
    roleName
    granular
  }
}

removeUserFromTeam

Instance admin only. Returns [UserTeamAccess!].

Take this person out of a team. Since node grants are scoped to a team, this is the one action that revokes all of them at once.

mutation {
  removeUserFromTeam(
    input: { userId: "user_9f1c2ab7d3e4f5a6", teamId: "team_9f1c2ab7d3e4f5a6", roleId: "role_9f1c2ab7d3e4f5a6" }
  ) {
    teamId
    roleName
    granular
  }
}

Registration links

registrationLinks

Instance admin only. Returns [RegistrationLink!].

Pending + recent registration links, newest first.

query {
  registrationLinks {
    id
    status
    mode
    expiresAt
  }
}

mintRegistrationLink

Instance admin only. Returns String.

Mint a single-use registration link. Returns the absolute /register URL.

mutation {
  mintRegistrationLink(
    input: { mode: existing_teams, teamAssignments: [{ teamId: "team_9f1c2ab7d3e4f5a6", role: member }] }
  )
}

revealRegistrationLink

Instance admin only. Returns String.

The full registration URL of a link that is still pending, so the admin who minted it can hand it over again instead of minting a second one. Errors, rather than returning a dead URL, when the link was used, revoked, expired, or minted before the token was stored encrypted.

mutation {
  revealRegistrationLink(id: "rlt_9f1c2ab7d3e4f5a6")
}

revokeRegistrationLink

Instance admin only. Returns Boolean.

Revoke a pending registration link. Returns true.

mutation {
  revokeRegistrationLink(id: "rlt_9f1c2ab7d3e4f5a6")
}

revokeAllRegistrationLinks

Instance admin only. Returns Int.

Revoke every pending registration link. Returns how many were revoked.

mutation {
  revokeAllRegistrationLinks
}

Creating an account

registerThroughLink

Public, no authentication. Returns AuthPayload.

Create a new account + team via a single-use registration link. Signs in.

mutation {
  registerThroughLink(
    token: "<token from the registration link>"
    email: "[email protected]"
    username: "ada"
    name: "Ada"
    password: "correct-horse-battery-staple"
  ) {
    viewer { id username }
  }
}

completeSetup

Public, no authentication. Returns AuthPayload.

First-run setup: create the first account + team. Signs in.

mutation {
  completeSetup(email: "[email protected]", name: "Ada", password: "correct-horse-battery-staple", teamName: "Acme") {
    viewer { id username }
  }
}

See also