Skip to main content

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
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.