Account

Everything on this page acts on the caller's own account. An API token is refused by all of it, whatever capabilities it holds: the answer is An API token can't access <that resource>. See Authentication for why a token is never a stand-in for the person who minted it.

The sign-in mutations are public. They set the session cookie the browser sends on every later request.

Identity

me

Public, no authentication. Returns Viewer.

The authenticated viewer, or null when unauthenticated. Works with a session cookie or an API token.

query {
  me {
    id
    username
    email
    isInstanceAdmin
  }
}

apiContext

Public, no authentication. Returns JSON.

Diagnostic: how the request authenticated and the active team. Useful when testing token auth.

query {
  apiContext
}

Signing in and out

A password login on an account with two-factor turned on answers requiresTwoFactor: true and no session. Finish it with verifyTwoFactorLogin. A passkey login is two steps too: passkeyChallenge, then verifyPasskeyLogin with what the authenticator produced.

login

Public, no authentication. Returns AuthPayload.

Sign in with email + password. Sets the session cookie.

mutation {
  login(email: "[email protected]", password: "correct-horse-battery-staple") {
    requiresTwoFactor
    viewer { id username }
  }
}

verifyTwoFactorLogin

Public, no authentication. Returns AuthPayload.

Finish a login that returned requiresTwoFactor, with a TOTP code or a recovery code.

mutation {
  verifyTwoFactorLogin(code: "123456") {
    viewer { id username }
  }
}

passkeyChallenge

Public, no authentication. Returns JSON.

Options for navigator.credentials.get. Public: this is the START of a sign-in, so there is no session yet.

mutation {
  passkeyChallenge
}

verifyPasskeyLogin

Public, no authentication. Returns AuthPayload.

Finish a passkey sign-in with what the authenticator produced. Sets the session cookie.

mutation {
  verifyPasskeyLogin(response: {}) {
    requiresTwoFactor
    viewer {
      id
      username
    }
  }
}

logout

Public, no authentication. Returns Boolean.

Clear the session + active-team cookies.

mutation {
  logout
}

Signed-in devices

mySessions

Any signed-in principal. Returns [UserSession!].

Every device currently signed in to the viewer's account, most recently seen first.

query {
  mySessions {
    id
    label
    browser
    os
    current
    lastSeenAt
  }
}

revokeSession

Any signed-in principal. Returns Boolean.

Sign one device out. Refuses the viewer's own session - use logout for that. Returns true.

mutation {
  revokeSession(id: "ses_9f1c2ab7d3e4f5a6")
}

revokeOtherSessions

Any signed-in principal. Returns Int.

Sign out every device except the one making the request, and return how many were ended.

mutation {
  revokeOtherSessions
}

Profile

updateProfile

Any signed-in principal. Returns Boolean.

Update the current user's display name, and their handle when one is given. The handle is the instance-wide public username: lowercase letters, numbers, - and _, 3-32 characters, unique. Returns true.

mutation {
  updateProfile(name: "Ada Lovelace", username: "ada")
}

updateEmail

Any signed-in principal. Returns Boolean.

Change the current user's email after re-checking their password. Returns true.

mutation {
  updateEmail(
    currentPassword: "correct-horse-battery-staple"
    email: "[email protected]"
  )
}

changePassword

Any signed-in principal. Returns Boolean.

Change the current user's password after verifying the current one. Returns true.

mutation {
  changePassword(
    currentPassword: "correct-horse-battery-staple"
    newPassword: "a-longer-new-passphrase"
  )
}

updateMyAvatar

Any signed-in principal. Returns Boolean.

Set the current user's picture SOURCE: a base64 image data-URI (png/jpeg/webp, downscaled to 256x256 by the browser as a convenience - the size and grammar are enforced here), <style>:<preset>:<seed> for a generated picture (pixelbot faces, initials monograms), gravatar, or initials for the monogram. Null or empty clears the choice, which falls back to their Gravatar (when the instance allows it) and then to a face seeded with their id. Returns true.

mutation {
  updateMyAvatar(image: "pixelbot:default:ada")
}

Two-factor authentication

startTwoFactorEnrolment

Any signed-in principal. Returns TwoFactorEnrolment.

Mint a TOTP secret and recovery codes. Requires the account password. Refused when two-factor is already on.

mutation {
  startTwoFactorEnrolment(password: "correct-horse-battery-staple") {
    totpUri
    recoveryCodes
  }
}

confirmTwoFactorEnrolment

Any signed-in principal. Returns Boolean.

Finish enrolment with the first code from the authenticator app. Turns two-factor on.

mutation {
  confirmTwoFactorEnrolment(code: "123456")
}

regenerateRecoveryCodes

Any signed-in principal. Returns [String!].

Replace every recovery code with a fresh set, returned once. Requires the password AND a current code.

mutation {
  regenerateRecoveryCodes(code: "123456", password: "correct-horse-battery-staple")
}

disableTwoFactor

Any signed-in principal. Returns Boolean.

Turn two-factor off. Requires the password AND a current code (a recovery code also works).

mutation {
  disableTwoFactor(code: "123456", password: "correct-horse-battery-staple")
}

Passkeys

myPasskeys

Any signed-in principal. Returns [Passkey!].

Passkeys registered on this account, newest first.

query {
  myPasskeys {
    id
    name
    kind
    createdAt
  }
}

startPasskeyRegistration

Any signed-in principal. Returns JSON.

Options for navigator.credentials.create. Requires the account password.

mutation {
  startPasskeyRegistration(password: "correct-horse-battery-staple")
}

finishPasskeyRegistration

Any signed-in principal. Returns Passkey.

Register the credential the authenticator produced. No password: the challenge it answers was minted behind one.

mutation {
  finishPasskeyRegistration(name: "MacBook Touch ID", response: { id: "…", rawId: "…", type: "public-key", response: { … } }) {
    id
    name
    kind
  }
}

renamePasskey

Any signed-in principal. Returns Boolean.

Relabel a passkey. A label is not a credential, so no password.

mutation {
  renamePasskey(id: "pk_9f1c2ab7d3e4f5a6", name: "MacBook Touch ID")
}

deletePasskey

Any signed-in principal. Returns Boolean.

Remove a passkey. Requires the account password, and refuses the last one while a team's two-factor policy rests on it.

mutation {
  deletePasskey(
    id: "pk_9f1c2ab7d3e4f5a6"
    password: "correct-horse-battery-staple"
  )
}

See also