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¶
The easiest way to explore it is by using graphQL.
Examples:
{
"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"
}
}
]
}
}
}
MeQuery¶
Since this query requires an authenticated user it can be explored by using the insomnia API client.
Example:
Mutations¶
All mutations can be imported like this:
Standard response¶
All mutations return a standard response containing errors
and success
.
- Example:
{
"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
}
}
}
Public¶
Public mutations don't require user to be logged in. You should add all of them in GRAPHQL_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 return unarchiving=True
on output.
{
"data": {
"tokenAuth": {
"success": true,
"errors": null,
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImV4cCI6MTU3OTQ1ODI2Niwib3JpZ0lhdCI6MTU3OTQ1Nzk2Nn0.BKz4ohxQCGtJWnyd5tIbYFD2kpGYDiAVzWTDO2ZyUYY",
"refreshToken": "5f5fad67cd043437952ddde2750be20201f1017b",
"unarchiving": false,
"user": {
"id": "VXNlck5vZGU6MQ==",
"username": "skywalker"
}
}
}
}
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.
{
"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"
}
]
}
}
}
}
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.
{
"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 as grapgql_jwt
implementation, with change exception error message from "Error decoding signature" to "Invalid token.".
{
"data": {
"refreshToken": {
"success": true,
"errors": null,
"payload": {
"username": "skywalker",
"exp": 1601646082,
"origIat": 1601645782
},
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImV4cCI6MTYwMTY0NjA4Miwib3JpZ0lhdCI6MTYwMTY0NTc4Mn0.H6gLeky7lX834kBI5RFT8ziNNfGOL3XXg1dRwvpQuRI",
"refreshToken": "a64f732b4e00432f2ff1b47537a11458be13fc82",
"refreshExpiresIn": 1602250582
}
}
}
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 a UserStatus
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.
{
"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
}
}
}
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.
RevokeToken¶
Same as grapgql_jwt
implementation, with change exception error message from "Error decoding signature" to "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.
graphql"Email fail" { "data": { "sendPasswordResetEmail": { "success": false, "errors": { "nonFieldErrors": [ { "message": "Failed to send email.", "code": "email_fail" } ] } } } }
VerifyAccount¶
Verify user account.
Receive the token that was sent by email. If the token is valid, make the user verified by making the user.status.verified
field true.
== "graphql"
mutation {
verifyAccount(
token:"eyJ1c2VybmFtZSI6InNreXdhbGtlciIsImFjdGlvbiI6ImFjdGl2YXRpb24ifQ:1itC5A:vJhRJwBcrNxvmEKxHrZa6Yoqw5Q",
) {
success, errors
}
}
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 to user.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.
VerifyToken¶
Same as grapgql_jwt
implementation, with change exception error message from "Error decoding signature" to "Invalid token.".
Protected¶
Protected mutations require the http Authorization header.
If you send a request without the http Authorization header, or a bad token:
- If using
graphql_jwt.backends.JSONWebTokenBackend
, it will raise. - If using
graphql_auth.backends.GraphQLAuthBackend
, it will return a standard response, withsuccess=False
anderrors
.
As explained on the installation guide
ArchiveAccount¶
Archive account and revoke refresh tokens.
User must be verified and confirm password.
DeleteAccount¶
Delete account permanently or make user.is_active=False
.
The behavior is defined on settings. Anyway user refresh tokens are revoked.
User must be verified and confirm password.
PasswordChange¶
Change account password when user knows the old password.
A new token and refresh token are sent. User must be verified.
{
"data": {
"passwordChange": {
"success": true,
"errors": null,
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImpvZWpvZSIsImV4cCI6MTU4MDE0MjE0MCwib3JpZ0lhdCI6MTU4MDE0MTg0MH0.BGUSGKUUd7IuHnWKy8V6MU3slJ-DHsyAdAjGrGb_9fw",
"refreshToken": "67eb63ba9d279876d3e9ae4d39c311e845e728fc"
}
}
}
{
"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
}
}
}
RemoveSecondaryEmail¶
Remove user secondary email.
Require password confirmation.
SendSecondaryEmailActivation¶
Send activation to secondary email.
User must be verified and confirm password.
SwapEmails¶
Swap between primary and secondary emails.
Require password confirmation.
UpdateAccount¶
Update user model fields, defined on settings.
User must be verified.
=== "graphql"
```graphql
mutation {
updateAccount(
firstName: "Luke"
) {
success,
errors
}
}
```