API

Query

GraphQL Auth provides the UserQuery to query users with some useful filters.

GraphQL Auth also provides the MeQuery to retrieve data for the currently authenticated user.

UserQuery

fromgraphql_auth.schemaimportUserQuery

The easiest way to explore it is by usinggraphiQL.

Examples from thequickstart:

query {  users {    edges {      node {        username,        archived,        verified,        email,        secondaryEmail,      }    }  }}
{"data":{"users":{"edges":[        {          "node": {            "username": "user1",            "archived": false,            "verified": false,            "email": "user1@email.com",            "secondaryEmail": null          }        },        {          "node": {            "username": "user2",            "archived": false,            "verified": true,            "email": "user2@email.com",            "secondaryEmail": null          }        },        {          "node": {            "username": "user3",            "archived": true,            "verified": true,            "email": "user3@email.com",            "secondaryEmail": null          }        },        {          "node": {            "username": "user4",            "archived": false,            "verified": true,            "email": "user4@email.com",            "secondaryEmail": "user4_secondary@email.com"          }        }]}}}
query {  users (last: 1){    edges {      node {        id,        username,        email,        isActive,        archived,        verified,        secondaryEmail      }    }  }}
{"data":{"users":{"edges":[        {          "node": {            "id": "VXNlck5vZGU6NQ==",            "username": "new_user",            "email": "new_user@email.com",            "isActive": true,            "archived": false,            "verified": false,            "secondaryEmail": null          }        }]}}}
query {  user (id: "VXNlck5vZGU6NQ=="){    username,    verified  }}
{  "data": {    "user": {      "username": "new_user",      "verified": true    }  }}

MeQuery

fromgraphql_auth.schemaimportMeQuery

Since this query requires an authenticated user it can be explored by using theinsomnia API client. See thequickstart for more on how to use Insomnia.

Example from thequickstart:

query {  me {    username,    verified  }}
{  "data": {    "user": {      "username": "new_user",      "verified": true    }  }}

Mutations

All mutations can be imported like this:

fromgraphql_authimportmutations# on your mutationsregister=mutations.Register
fromgraphql_authimportrelay# on your mutationsregister=userelay.Register

Standard response

All mutations return a standard response containingerrors andsuccess.

  • Example:
mutation{register(email:"new_user@email.com",username:"new_user",password1:"123456",password2:"123456",){success,errors,token,refreshToken}}
{"data":{"register":{"success":false,"errors":{"password2":[{"message":"This password is too short. It must contain at least 8 characters.","code":"password_too_short"},{"message":"This password is too common.","code":"password_too_common"},{"message":"This password is entirely numeric.","code":"password_entirely_numeric"}]},"token":null"refreshToken":null}}}
mutation{register(input:{email:"new_user@email.com",username:"new_user",password1:"123456",password2:"123456",}){success,errors,token,refreshToken}}

Public

Public mutations don't require user to be logged in. You should add all of them inGRAPHQL_JWT["JWT_ALLOW_ANY_CLASSES"] setting.

ObtainJSONWebToken

Obtain JSON web token for given user.

Allow to perform login with different fields, and secondary email if set. The fields are defined on settings.

Not verified users can login by default. This can be changes on settings.

If user is archived, make it unarchive and returnunarchiving=True on output.

mutation{  tokenAuth(# username or email    email:"skywalker@email.com"    password:"123456super"){    success,    errors,    token,    refreshToken,    unarchiving,    user{      id,      username}}}
{"data":{"tokenAuth":{"success": true,"errors": null,"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImV4cCI6MTU3OTQ1ODI2Niwib3JpZ0lhdCI6MTU3OTQ1Nzk2Nn0.BKz4ohxQCGtJWnyd5tIbYFD2kpGYDiAVzWTDO2ZyUYY","refreshToken":"5f5fad67cd043437952ddde2750be20201f1017b","unarchiving": false,"user":{"id":"VXNlck5vZGU6MQ==","username":"skywalker"}}}}
mutation{  tokenAuth(    input:{      email:"skywalker@email.com"      password:"123456super"}){    success,    errors,    token,    refreshToken,    user{      id,      username}}}
{"data":{"tokenAuth":{"success": false,"errors":{"nonFieldErrors":[{"message":"Please, enter valid credentials.","code":"invalid_credentials"}]},"token": null,"refreshToken": null,"unarchiving": false,"user": null}}}

PasswordSet

Set user password - for passwordless registration

Receive the token that was sent by email.

If token and new passwords are valid, set user password and in case of using refresh tokens, revoke all of them.

Also, if user has not been verified yet, verify it.

mutation{  passwordSet(    token:"1eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImFjdGlvbiI6InBhc3N3b3JkX3Jlc2V0In0:1itExL:op0roJi-ZbO9cszNEQMs5mX3c6s",    newPassword1:"supersecretpassword",    newPassword2:"supersecretpassword"){    success,    errors}}
{"data":{"passwordSet":{"success": true,"errors": null}}}
mutation{  passwordSet(    input:{      token:"1eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImFjdGlvbiI6InBhc3N3b3JkX3Jlc2V0In0:1itExL:op0roJi-ZbO9cszNEQMs5mX3c6s",      newPassword1:"supersecretpassword",      newPassword2:"supersecretpassword"}){    success,    errors}}
{"data":{"passwordSet":{"success": false,"errors":{"nonFieldErrors":[{"message":"Invalid token.","code":"invalid_token"}]}}}}
{"data":{"passwordSet":{"success": false,"errors":{"newPassword2":[{"message":"The two password fields didn’t match.","code":"password_mismatch"}]}}}}
{"data":{"passwordSet":{"success": false,"errors":{"newPassword2":[{"message":"This password is too short. It must contain at least 8 characters.","code":"password_too_short"},{"message":"This password is too common.","code":"password_too_common"},{"message":"This password is entirely numeric.","code":"password_entirely_numeric"}]}}}}
{"data":{"passwordSet":{"success": false,"errors":{"nonFieldErrors":[{"message":"Password already set for account.","code":"password_already_set"}]}}}}

PasswordReset

Change user password without old password.

Receive the token that was sent by email.

If token and new passwords are valid, update user password and in case of using refresh tokens, revoke all of them.

Also, if user has not been verified yet, verify it.

mutation{  passwordReset(    token:"1eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImFjdGlvbiI6InBhc3N3b3JkX3Jlc2V0In0:1itExL:op0roJi-ZbO9cszNEQMs5mX3c6s",    newPassword1:"supersecretpassword",    newPassword2:"supersecretpassword"){    success,    errors}}
{"data":{"passwordReset":{"success": true,"errors": null}}}
mutation{  passwordReset(    input:{      token:"1eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImFjdGlvbiI6InBhc3N3b3JkX3Jlc2V0In0:1itExL:op0roJi-ZbO9cszNEQMs5mX3c6s",      newPassword1:"supersecretpassword",      newPassword2:"supersecretpassword"}){    success,    errors}}
{"data":{"passwordReset":{"success": false,"errors":{"nonFieldErrors":[{"message":"Invalid token.","code":"invalid_token"}]}}}}
{"data":{"passwordReset":{"success": false,"errors":{"newPassword2":[{"message":"The two password fields didn’t match.","code":"password_mismatch"}]}}}}
{"data":{"passwordReset":{"success": false,"errors":{"newPassword2":[{"message":"This password is too short. It must contain at least 8 characters.","code":"password_too_short"},{"message":"This password is too common.","code":"password_too_common"},{"message":"This password is entirely numeric.","code":"password_entirely_numeric"}]}}}}

RefreshToken

Same asgrapgql_jwt implementation, with standard output.

mutation{  refreshToken(    refreshToken:"d9b58dce41cf14549030873e3fab3be864f76ce44"){    success,    errors,    payload,    refreshExpiresIn,    token,    refreshToken}}
{"data":{"refreshToken":{"success": true,"errors": null,"payload":{"username":"skywalker","exp":1601646082,"origIat":1601645782},"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImV4cCI6MTYwMTY0NjA4Miwib3JpZ0lhdCI6MTYwMTY0NTc4Mn0.H6gLeky7lX834kBI5RFT8ziNNfGOL3XXg1dRwvpQuRI","refreshToken":"a64f732b4e00432f2ff1b47537a11458be13fc82","refreshExpiresIn":1602250582}}}
mutation{  refreshToken(    input:{      refreshToken:"d9b58dce41cf14549030873e3fab3be864f76ce44"}){    success,    errors,    payload,    refreshExpiresIn,    token,    refreshToken}}
{"data":{"refreshToken":{"success": false,"errors":{"nonFieldErrors":[{"message":"Invalid token.","code":"invalid_token"}]}}}}

Register

Register user with fields defined in the settings.

If the email field of the user model is part of the registration fields (default), check if there is no user with that email or as a secondary email.

If it exists, it does not register the user, even if the email field is not defined as unique (default of the default django user model).

When creating the user, it also creates aUserStatus related to that user, making it possible to track if the user is archived, verified and has a secondary email.

Send account verification email.

If allowed to not verified users login, return token.

mutation{  register(    email:"skywalker@email.com",    username:"skywalker",    password1:"qlr4nq3f3",    password2:"qlr4nq3f3"){    success,    errors,    token,    refreshToken}}
{"data":{"register":{"success": true,"errors": null,"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImpvZWpvZSIsImV4cCI6MTU4MDE0MjE0MCwib3JpZ0lhdCI6MTU4MDE0MTg0MH0.BGUSGKUUd7IuHnWKy8V6MU3slJ-DHsyAdAjGrGb_9fw","refreshToken":"d9b58dce41cf14549030873e3fab3be864f76ce44"}}}
mutation{  register(    input:{      email:"skywalker@email.com",      username:"skywalker",      password1:"qlr4nq3f3",      password2:"qlr4nq3f3"}){    success,    errors,    token,    refreshToken}}
{"data":{"register":{"success": false,"errors":{"username":[{"message":"A user with that username already exists.","code":"unique"}]},"token": null,"refreshToken": null}}}
{"data":{"register":{"success": false,"errors":{"password2":[{"message":"The two password fields didn’t match.","code":"password_mismatch"}]},"token": null,"refreshToken": null}}}
{"data":{"register":{"success": false,"errors":{"password2":[{"message":"This password is too short. It must contain at least 8 characters.","code":"password_too_short"},{"message":"This password is too common.","code":"password_too_common"},{"message":"This password is entirely numeric.","code":"password_entirely_numeric"}]},"token": null,"refreshToken": null}}}
{"data":{"register":{"success": false,"errors":{"email":[{"message":"Enter a valid email address.","code":"invalid"}]},"token": null,"refreshToken": null}}}

ResendActivationEmail

Sends activation email.

It is called resend because theoretically the first activation email was sent when the user registered.

If there is no user with the requested email, a successful response is returned.

mutation{  resendActivationEmail(    email:"skywalker@email.com",){    success,    errors}}
{"data":{"register":{"success": true,"errors": null}}}
mutation{  resendActivationEmail(    input:{      email:"skywalker@email.com",}){    success,    errors}}
{"data":{"resendActivationEmail":{"success": false,"errors":{"email":[[{"message":"Account already verified.","code":"already_verified"}]]}}}}
{"data":{"resendActivationEmail":{"success": false,"errors":{"email":[{"message":"Enter a valid email address.","code":"invalid"}]}}}}
{"data":{"resendActivationEmail":{"success": false,"errors":{"nonFieldErrors":[{"message":"Failed to send email.","code":"email_fail"}]}}}}

RevokeToken

Same asgrapgql_jwt implementation, with standard output.

mutation{  revokeToken(    refreshToken:"a64f732b4e00432f2ff1b47537a11458be13fc82"){    success,    errors}}
{"data":{"revokeToken":{"success": true,"errors": null}}}
mutation{  revokeToken(    input:{      refreshToken:"a64f732b4e00432f2ff1b47537a11458be13fc82"}){    success,    errors}}
{"data":{"revokeToken":{"success": false,"errors":{"nonFieldErrors":[{"message":"Invalid token.","code":"invalid_token"}]}}}}

SendPasswordResetEmail

Send password reset email.

For non verified users, send an activation email instead.

Accepts both primary and secondary email.

If there is no user with the requested email, a successful response is returned.

mutation{  sendPasswordResetEmail(    email:"skywalker@email.com"){    success,    errors}}
{"data":{"register":{"success": true,"errors": null}}}
mutation{  sendPasswordResetEmail(    input:{      email:"skywalker@email.com"}){    success,    errors}}
{"data":{"sendPasswordResetEmail":{"success": false,"errors":{"email":[{"message":"Enter a valid email address.","code":"invalid"}]}}}}
{"data":{"sendPasswordResetEmail":{"success": false,"errors":{"nonFieldErrors":[{"message":"Failed to send email.","code":"email_fail"}]}}}}
{"data":{"sendPasswordResetEmail":{"success": false,"errors":{"email":[{"message":"Verify your account. A new verification email was sent.","code":"not_verified"}]}}}}

VerifyAccount

Verify user account.

Receive the token that was sent by email. If the token is valid, make the user verified by making theuser.status.verified field true.

mutation{  verifyAccount(    token:"eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImFjdGlvbiI6ImFjdGl2YXRpb24ifQ:1itC5A:vJhRJwBcrNxvmEKxHrZa6Yoqw5Q",){    success, errors}}
{"data":{"verifyAccount":{"success": true,"errors": null}}}
mutation{  verifyAccount(    input:{      token:"eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImFjdGlvbiI6ImFjdGl2YXRpb24ifQ:1itC5A:vJhRJwBcrNxvmEKxHrZa6Yoqw5Q",}){    success, errors}}
{"data":{"verifyAccount":{"success": false,"errors":{"nonFieldErrors":[{"message":"Invalid token.","code":"invalid_token"}]}}}}
{"data":{"verifyAccount":{"success": false,"errors":{"nonFieldErrors":[{"message":"Account already verified.","code":"already_verified"}]}}}}

VerifySecondaryEmail

Verify user secondary email.

Receive the token that was sent by email. User is already verified when using this mutation.

If the token is valid, add the secondary email touser.status.secondary_email field.

Note that until the secondary email is verified, it has not been saved anywhere beyond the token, so it can still be used to create a new account. After being verified, it will no longer be available.

mutation{  verifySecondaryEmail(    token:"eyJ1c2VybmFtZSI6Im5ld191c2VyMSIsImFjdGlvbiI6ImFjdGl2YXRpb25fc2Vjb25kYXJ5X2VtYWlsIiwic2Vjb25kYXJ5X2VtYWlsIjoibXlfc2Vjb25kYXJ5X2VtYWlsQGVtYWlsLmNvbSJ9:1ivhfJ:CYZswRKV3avWA8cb41KqZ1-zdVo"){    success, errors}}
{"data":{"verifySecondaryEmail":{"success": true,"errors": null}}}
mutation{  verifySecondaryEmail(    input:{      token:"eyJ1c2VybmFtZSI6Im5ld191c2VyMSIsImFjdGlvbiI6ImFjdGl2YXRpb25fc2Vjb25kYXJ5X2VtYWlsIiwic2Vjb25kYXJ5X2VtYWlsIjoibXlfc2Vjb25kYXJ5X2VtYWlsQGVtYWlsLmNvbSJ9:1ivhfJ:CYZswRKV3avWA8cb41KqZ1-zdVo"}){    success, errors}}
{"data":{"verifySecondaryEmail":{"success": false,"errors":{"nonFieldErrors":[{"message":"Invalid token.","code":"invalid_token"}]}}}}
{"data":{"verifySecondaryEmail":{"success": false,"errors":{"nonFieldErrors":[{"message":"Expired token.","code":"expired_token"}]}}}}

VerifyToken

Same asgrapgql_jwt implementation, with standard output.

mutation{  verifyToken(    token:"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImV4cCI6MTU3OTQ1ODY3Miwib3JpZ0lhdCI6MTU3OTQ1ODM3Mn0.rrB4sMA-v7asrr8Z2ru69U1x-d98DuEJVBnG2F1C1S0"){    success,    errors,    payload}}
{"data":{"verifyToken":{"success": true,"errors": null,"payload":{"username":"skywalker","exp":1579458672,"origIat":1579458372}}}}
mutation{  verifyToken(    input:      token:"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImV4cCI6MTU3OTQ1ODY3Miwib3JpZ0lhdCI6MTU3OTQ1ODM3Mn0.rrB4sMA-v7asrr8Z2ru69U1x-d98DuEJVBnG2F1C1S0"}){    success,    errors,    payload}}
{"data":{"verifyToken":{"success": false,"errors":{"nonFieldErrors":[{"message":"Invalid token.","code":"invalid_token"}]},"payload": null}}}
{"data":{"verifyToken":{"success": false,"errors":{"nonFieldErrors":[{"message":"Expired token.","code":"expired_token"}]}}}}

Protected

Protected mutations require the http Authorization header.

If you send a requestwithout the http Authorization header, or abad token:

  • If usinggraphql_jwt.backends.JSONWebTokenBackend, it will raise.
  • If usinggraphql_auth.backends.GraphQLAuthBackend, it will return a standard response, withsuccess=False anderrors.

As explained on theinstallation guide

ArchiveAccount

Archive account and revoke refresh tokens.

User must be verified and confirm password.

mutation{  archiveAccount(    password:"supersecretpassword",){    success,    errors}}
{"data":{"register":{"success": true,"errors": null}}}
mutation{  archiveAccount(    input:{      password:"supersecretpassword",}){    success,    errors}}
{"data":{"archiveAccount":{"success": false,"errors":{"nonFieldErrors":[{"message":"Unauthenticated.","code":"unauthenticated"}]}}}}
{"data":{"archiveAccount":{"success": false,"errors":{"password":[{"message":"Invalid password.","code":"invalid_password"}]}}}}
{"data":{"archiveAccount":{"success": false,"errors":{"nonFieldErrors":[{"message":"Please verify your account.""code":"not_verified"}]}}}}

DeleteAccount

Delete account permanently or makeuser.is_active=False.

The behavior is defined on settings. Anyway user refresh tokens are revoked.

User must be verified and confirm password.

mutation{  deleteAccount(    password:"supersecretpassword",){    success,    errors}}
{"data":{"deleteAccount":{"success": true,"errors": null}}}
mutation{  deleteAccount(    input:{      password:"supersecretpassword",}){    success,    errors}}
{"data":{"deleteAccount":{"success": false,"errors":{"nonFieldErrors":[{"message":"Unauthenticated.","code":"unauthenticated"}]}}}}
{"data":{"deleteAccount":{"success": false,"errors":{"password":[{"message":"Invalid password.","code":"invalid_password"}]}}}}
{"data":{"deleteAccount":{"success": false,"errors":{"nonFieldErrors":[{"message":"Please verify your account.""code":"not_verified"}]}}}}

PasswordChange

Change account password when user knows the old password.

A new token and refresh token are sent. User must be verified.

mutation{ passwordChange(    oldPassword:"supersecretpassword",    newPassword1:"123456super",     newPassword2:"123456super"){    success,    errors,    token,    refreshToken}}
{"data":{"passwordChange":{"success": true,"errors": null,"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImpvZWpvZSIsImV4cCI6MTU4MDE0MjE0MCwib3JpZ0lhdCI6MTU4MDE0MTg0MH0.BGUSGKUUd7IuHnWKy8V6MU3slJ-DHsyAdAjGrGb_9fw","refreshToken":"67eb63ba9d279876d3e9ae4d39c311e845e728fc"}}}
mutation{ passwordChange(   input:{      oldPassword:"supersecretpassword",      newPassword1:"123456super",       newPassword2:"123456super"}){    success,    errors,    token,    refreshToken}}
{"data":{"passwordChange":{"success": false,"errors":{"nonFieldErrors":[{"message":"Unauthenticated.","code":"unauthenticated"}]},"token": null,"refreshToken": null}}}
{"data":{"passwordChange":{"success": false,"errors":{"nonFieldErrors":[{"message":"Please verify your account.""code":"not_verified"}]},"token": null,"refreshToken": null}}}
{"data":{"passwordChange":{"success": false,"errors":{"newPassword2":[{"message":"This password is too short. It must contain at least 8 characters.","code":"password_too_short"},{"message":"This password is too common.","code":"password_too_common"},{"message":"This password is entirely numeric.","code":"password_entirely_numeric"}]},"token": null,"refreshToken": null}}}
{"data":{"passwordChange":{"success": false,"errors":{"newPassword2":[{"message":"The two password fields didn’t match.","code":"password_mismatch"}]},"token": null,"refreshToken": null}}}
{"data":{"passwordChange":{"success": false,"errors":{"oldPassword":[{"message":"Invalid password.","code":"invalid_password"}]},"token": null,"refreshToken": null}}}

RemoveSecondaryEmail

Remove user secondary email.

Require password confirmation.

mutation{  removeSecondaryEmail(    password:"supersecretpassword"){    success,    errors}}
{"data":{"removeSecondaryEmail":{"success": true,"errors": null}}}
mutation{  removeSecondaryEmail(    input:{      password:"supersecretpassword"}){    success,    errors}}
{"data":{"removeSecondaryEmail":{"success": false,"errors":{"password":[{"message":"Invalid password.","code":"invalid_password"}]}}}}

SendSecondaryEmailActivation

Send activation to secondary email.

User must be verified and confirm password.

mutation{  sendSecondaryEmailActivation(    email:"my_secondary_email@email.com"    password:"supersecretpassword",){    success,    errors}}
{"data":{"sendSecondaryEmailActivation":{"success": true,"errors": null}}}
mutation{  sendSecondaryEmailActivation(    input:{      email:"my_secondary_email@email.com"      password:"supersecretpassword",}){    success,    errors}}
{"data":{"sendSecondaryEmailActivation":{"success": false,"errors":{"nonFieldErrors":[{"message":"Unauthenticated.","code":"unauthenticated"}]}}}}
{"data":{"sendSecondaryEmailActivation":{"success": false,"errors":{"email":[{"message":"Enter a valid email address.","code":"invalid"}]}}}}
{"data":{"sendSecondaryEmailActivation":{"success": false,"errors":{"password":[{"message":"Invalid password.","code":"invalid_password"}]}}}}
{"data":{"sendSecondaryEmailActivation":{"success": false,"errors":{"nonFieldErrors":[{"message":"Please verify your account.""code":"not_verified"}]}}}}

SwapEmails

Swap between primary and secondary emails.

Require password confirmation.

mutation{  swapEmails(    password:"supersecretpassword"){    success,    errors}}
{"data":{"swapEmails":{"success": true,"errors": null}}}
mutation{  swapEmails(    input:{      password:"supersecretpassword"}){    success,    errors}}
{"data":{"swapEmails":{"success": false,"errors":{"password":[{"message":"Invalid password.","code":"invalid_password"}]}}}}

UpdateAccount

Update user model fields, defined on settings.

User must be verified.

mutation{  updateAccount(    firstName:"Luke"){    success,    errors}}
{"data":{"updateAccount":{"success": true,"errors": null}}}
mutation{  updateAccount(    input:{      firstName:"Luke"}){    success,    errors}}
{"data":{"updateAccount":{"success": false,"errors":{"nonFieldErrors":[{"message":"Unauthenticated.","code":"unauthenticated"}]}}}}
{"data":{"updateAccount":{"success": false,"errors":{"nonFieldErrors":[{"message":"Please verify your account.""code":"not_verified"}]}}}}