Endpoint | Method | Description |
---|---|---|
/auth/register | POST | Register user |
/auth/login | POST | Login user |
/auth/logout | POST | Logout user |
/auth/activate | POST | Activate user |
/auth/token/refresh | GET | Get new refresh token |
/auth/token/revoke | POST | Revoke refresh token |
/auth/delete | POST | Delete user |
Endpoint | Method | Description |
---|---|---|
/auth/change-password/ | POST | Change password as logged in |
/auth/change-password/request | POST | Request to change password |
/auth/change-password/change | POST | Change password with ticket |
Endpoint | Method | Description |
---|---|---|
/auth/change-email/ | POST | Change email as logged in |
/auth/change-email/request | POST | Request to change email |
/auth/change-email/change | POST | Change email with ticket |
Endpoint | Method | Description |
---|---|---|
/auth/mfa/generate | POST | Generate MFA QR-code |
/auth/mfa/enable | POST | Enable MFA |
/auth/mfa/disable | POST | Disable MFA |
/auth/mfa/totp | POST | TOTP login |
Register a new user.
auth.register({ email, password });
With custom user_data, for ex display_name
:
auth.register({
email,
password,
options: {
userData: {
display_name: "Joe Doe",
},
},
});
POST /auth/register
{
"email": "elon@tesla.com",
"password": "password"
}
With custom user_data, for ex display_name
:
{
"email": "elon@tesla.com",
"password": "password",
"user_data": {
"display_name": "Elon Musk"
}
}
{
"session": {
"jwt_token": "e3MmYZSJdLCJ4LWhhjE0MDg3Nzc3fQ.d4kdsiBjD3MpPpbNNbaMt-gyHHVXwrSvrAtVcEQ_jB8",
"jwt_expires_in": 900000,
"user": {
"id": "kcf72f45-5a2d-4615-810d-96e10548bb35",
"display_name": "nuno@nhost.io",
"email": "nuno@nhost.io"
},
"refresh_token": "dd69aafd-71f6-4f97-be93-9bdbfb192fe6"
},
"user": {
"id": "kcf72f45-5a2d-4615-810d-96e10548bb35",
"display_name": "nuno@nhost.io",
"email": "nuno@nhost.io"
}
}
If
AUTO_ACTIVATE_NEW_USERS
isfalse
,session
will returnnull
.
Login user
auth.login({ email, password });
POST /auth/login
{
"email": "marc@facebook.com",
"password": "password"
}
Set-Cookie: refresh_token=...
Set-Cookie: permission_variables=...
{
"session": {
"jwt_token": "e3MmYZSJdLCJ4LWhhjE0MDg3Nzc3fQ.d4kdsiBjD3MpPpbNNbaMt-gyHHVXwrSvrAtVcEQ_jB8",
"jwt_expires_in": 900000,
"user": {
"id": "kcf72f45-5a2d-4615-810d-96e10548bb35",
"display_name": "nuno@nhost.io",
"email": "nuno@nhost.io"
},
"refresh_token": "dd69aafd-71f6-4f97-be93-9bdbfb192fe6"
},
"user": {
"id": "kcf72f45-5a2d-4615-810d-96e10548bb35",
"display_name": "nuno@nhost.io",
"email": "nuno@nhost.io"
}
}
If Multi-Factor Authentication (MFA) is enabled for the account, the following response body is returned:
{
"session": null,
"user": null,
"mfa": {
"ticket": "762ea295-4a12-436f-b8fc-36b91aefb28e"
}
}
For login with MFA, proceed authentication by requesting the TOTP /auth/mfa/totp endpoint.
Logout user.
auth.logout(all: boolean = false);
POST /auth/login?all=<boolean = false>
if all = true
all of the user's refresh token will be revoked from the database, effectevly logging out the user from all devices. If all = false
only the current refresh token will be deleted and the user will only logout from the current device. all
is optional and defaults to false
.
{
"session": null,
"user": null
}
Activate user.
This is only needed if users is not automatically activated. If users are not automatically activated Nhost will send an email, containing the activation URL, to the user to activate their account. The email template for account activate can be edited.
auth.activate(ticket: string);
POST /auth/activate?ticket=<ticket>
204 No Content
When a user login Nhost will set a refresh-token as a cookie. That refresh-token is used to request a new JWT-token, since JWT-tokens are short lived (15 min). Refresh-tokens are long lived (1 year).
The refresh-token cookie is a Secure
HttpOnly
cookie and can not be accessed by the browser because only Nhost should be able to read the cookie.
nhost-js-sdk
automatically handle refreshing-tokens for logged in users in the background. No action required.
GET /auth/token/refresh
Cookie: refresh_token=<current_refresh_token>
Cookie: refresh_token=<new_refresh_token>
{
"session": {
"jwt_token": "e3MmYZSJdLCJ4LWhhjE0MDg3Nzc3fQ.d4kdsiBjD3MpPpbNNbaMt-gyHHVXwrSvrAtVcEQ_jB8",
"jwt_expires_in": 900000,
"user": {
"id": "kcf72f45-5a2d-4615-810d-96e10548bb35",
"display_name": "nuno@nhost.io",
"email": "nuno@nhost.io"
},
"refresh_token": "dd69aafd-71f6-4f97-be93-9bdbfb192fe6"
},
"user": {
"id": "kcf72f45-5a2d-4615-810d-96e10548bb35",
"display_name": "nuno@nhost.io",
"email": "nuno@nhost.io"
}
}
Revoke a refresh-token.
not implemented
GET /auth/token/refresh
Cookie: refresh_token=<current_refresh_token>
204 No Content
Used so user can delete themselves. This will delete the user in the users
table which will cascade and delete all associated data for the particular user if ON DELETE CASCADE
is set for Foreign keys.
This endpoint is only active if you allow users to delete themselves in Settings -> Authentication. (Not implemented yet, default value is Not active)
not implemented
POST /auth/delete
Set-Cookie: refresh_token=...
Set-Cookie: permission_variables=...
204 No Content
For users to change their password when they are logged in and remember their previous password.
auth.changePassword(oldPassword: string, newPassword: string);
POST /auth/change-password
Set-Cookie: refresh_token=...
Set-Cookie: permission_variables=...
{
"old_password": "<old password>",
"new_password": "<new password>"
}
204 No Content
If a user has forget their password they can request to change their password.
An email will be sent out to the user with a ticket
that should be used to update the user's password. You can change the password reset email template.
auth.requestPasswordChange(email: string);
POST /auth/change-password/request
{
"email": "<user's email>"
}
204 No Content
This endpoint will always return HTTP status code 204 in order to not leak information about the database.
Change password with ticket from the email.
auth.confirmPasswordChange(newPassword: string, ticket: string);
POST /auth/change-password/change
{
"new_password": "<new password>",
"ticket": "<ticket>"
}
204 No Content
Generate MFA (Multi-Factor Authentication) QR-code. The user must be logged in to generate this QR-code. The user should scan the QR-code with their password manager. The password manager will return a code
(one-time password) that will be used to enable and disable MFA for the user and login the user using TOTP login.
auth.MFAGenerate(code: string, ticket: string);
POST /auth/mfa/generate
{
"image_url": "<base64 data image of the qe code>",
"otp_secret": "<otp secret>"
}
Enable MFA (Multi-Factor Authentication). Use the code
(one-time password) in the user's password manager
auth.MFAEnable(code: string);
POST /auth/mfa/enable
{
"code": "123456"
}
204 No Content
Disable MFA (Multi-Factor Authentication). Use the code
(one-time password) in the user's password manager
Not implemented yet
POST /auth/mfa/disable
{
"code": "code from mfa client"
}
204 No Content
Time-based One-Time Password login. Use the ticket
from Login response body and the code
from the user's password manager.
auth.MFATotp(code: string, ticket: string);
POST /auth/mfa/generate
{
"image_url": "<base64 data image of the qe code>",
"otp_secret": "<otp secret>"
}