Manage user accounts

Introduction

This guide describes how to use the Karrio GraphQL API to register a new user account and do common account management operations.

Creating a new user account

Depending on the configuration of your Karrio server instance, registering a user account may be a single-step operation or it may require email confirmation to activate the account.

info

Karrio automatically require an email confirmation if the an email server is configured.

Karrio Email Config

You can configure your Karrio email server at http://localhost:5002/admin/constance/config/

• EMAIL_USE_TLS
• EMAIL_HOST_USER
• EMAIL_HOST_PASSWORD
• EMAIL_HOST
• EMAIL_PORT
• EMAIL_PAGE_DOMAIN
• EMAIL_FROM_ADDRESS

The EMAIL_PAGE_DOMAIN should be set to the domain name of your Karrio dashboard.

Register an account

Yes

Yes

Activation required?

Activation required?

Ask user to check their email

Ask user to check their email

Confirm account using token

Confirm account using token

New account is active

New account is active

User clicks link with token

User clicks link with token

Viewer does not support full SVG 1.1

Registration

To create a new user account, use the accountRegister mutation. The mutation takes the following input fields:

• email: user's email address.
• password1: user's password.
• password2: user's password confirmation.
• full_name: optionally, user's full name.

mutation {
  register_user(
    input: {
      email: "user@example.com"
      password1: "password"
      password2: "password"
      full_name: "John Doe"
    }
  ) {
    user {
      email
      is_staff
      date_joined
    }
    errors {
      field
      messages
    }
  }
}

As mentioned above, if the you have configured the karrio server email settings, the user will receive an email with a link to activate their account.

http://localhost:3000/email/YWxleC5taWxsZXIyNEBvdXRsb29rLmNvbQ-axd6yl-ce379fa50ced5079908ab669cabb456a89f441c2

The link contains a token which is required to proceed with the second mutation, confirm_email:

mutation confirm_email($data: { token: string;! }!) {
  confirm_email(input: $data) {
    success
  }
}

If the token is valid, the user will be successfully activated.

Accessing information about the authenticated user

The user query allows you to get information about currently logged in user.

{
  user {
    email
    full_name
    is_staff
    last_login
    date_joined
  }
}

response

{
  "data": {
    "user": {
      "email": "admin@karrio.io",
      "full_name": "Admin",
      "is_staff": true,
      "last_login": "2021-12-15T22:32:34.229203+00:00",
      "date_joined": "2021-01-07T23:32:10+00:00"
    }
  }
}

Accessing the private server API Key

The token query allows you to get the private key of the currently logged in user.

{
  token {
    key
  }
}

response

{
  "data": {
    "token": {
      "key": "key_0csfjeroij4i5jo9c2adb1e444lk867"
    }
  }
}

You can revoke and regenerate the API key using the mutate_token mutation.

mutation {
  mutate_token(input: { refresh: true }) {
    token {
      key
    }
  }
}

response

{
  "data": {
    "mutate_token": {
      "token": {
        "key": "key_6d956c1f9d093a5d2fd3dc0555452253"
      }
    }
  }
}

Resetting the password

Resetting the password is a two-step operation. First, you need to call a mutation to send an email with a unique link to reset the password.

The mutation takes the following input fields:

• email: user's email address.
• redirect_url: path to a view where the user should be redirected to reset the password.

mutation {
  request_password_reset(
    input: {
      email: "test@example.com"
      redirect_url: "localhost:3000/password/reset"
    }
  ) {
    errors {
      field
      messages
    }
  }
}

As a result, if there are no errors in the response, the system sends an email to user@example.com with a link to provide a new password, for example:

http://localhost:3000/password/reset?uidb64=Mw&token=ax10pr-af2cc4352f19713547b12ab0dd6c0661

The link contains two query parameters— uidb64 and token — which are required to proceed with the second mutation, confirm_password_reset.

The mutation takes the following input fields:

• uid: user's db id hashed in base64.
• token: a unique token that was included in the link in the email.
• new_password1: the new password.
• new_password1: the new password's confirmation.

mutation {
  confirm_password_reset(
    input: {
      uid: "Mw"
      token: "ax10pr-af2cc4352f19713547b12ab0dd6c0661"
      new_password1: "new-password"
      new_password2: "new-password"
    }
  ) {
    errors {
      field
      messages
    }
  }
}

If there are no errors in the response, the password is successfully changed.

Changing the password

If you wish to change your password as an authenticated user, use the change_password mutation. The mutation takes the following input fields:

• old_password: the current user's password.
• new_password1: the new password.
• new_password2: the new password confirmation.

mutation {
  change_password(
    input: {
      old_password: "current-password"
      new_password1: "new-password"
      new_password2: "new-password"
    }
  ) {
    errors {
      field
      messages
    }
  }
}

If no errors were returned, the password was changed successfully.

Changing the user info

Changing an email address or the full name of existing user accounts can be done with a single request. You need to call the update_user mutation.

The mutation takes the following input fields:

• email: the new email address to set for the account.
• full_name: the new full name to set for the account.

mutation {
  update_user(input: { email: "new-user@example.com", full_name: "Jane Doe" }) {
    email
    full_name
    errors {
      field
      messages
    }
  }
}

If no errors were returned, the email and full name were changed successfully.