API Reference for Nhost Authentication

#User

EndpointMethodDescription
/auth/registerPOSTRegister user
/auth/loginPOSTLogin user
/auth/logoutPOSTLogout user
/auth/activatePOSTActivate user
/auth/token/refreshGETGet new refresh token
/auth/token/revokePOSTRevoke refresh token
/auth/deletePOSTDelete user

#Password

EndpointMethodDescription
/auth/change-password/POSTChange password as logged in
/auth/change-password/requestPOSTRequest to change password
/auth/change-password/changePOSTChange password with ticket

#Email

EndpointMethodDescription
/auth/change-email/POSTChange email as logged in
/auth/change-email/requestPOSTRequest to change email
/auth/change-email/changePOSTChange email with ticket

#MFA (Multi-Factor Authentication)

EndpointMethodDescription
/auth/mfa/generatePOSTGenerate MFA QR-code
/auth/mfa/enablePOSTEnable MFA
/auth/mfa/disablePOSTDisable MFA
/auth/mfa/totpPOSTTOTP login

#Register user

Register a new user.

nhost-js-sdk

auth.register({ email, password });

With custom user_data, for ex display_name:

auth.register({
  email,
  password,
  options: {
    userData: {
      display_name: "Joe Doe",
    },
  },
});

Request

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"
  }
}

Response

{
  "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 is false, session will return null.


#Login user

Login user

nhost-js-sdk

auth.login({ email, password });

Request

POST /auth/login

{
  "email": "marc@facebook.com",
  "password": "password"
}

Response

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

Logout user.

nhost-js-sdk

auth.logout(all: boolean = false);

Request

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.

Response

{
  "session": null,
  "user": null
}

#Activate user

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.

nhost-js-sdk

auth.activate(ticket: string);

Request

POST /auth/activate?ticket=<ticket>

Response

204 No Content

#Get refresh token

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

nhost-js-sdk automatically handle refreshing-tokens for logged in users in the background. No action required.

Request

GET /auth/token/refresh

Cookie: refresh_token=<current_refresh_token>

Response

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 refresh-token

Revoke a refresh-token.

nhost-js-sdk

not implemented

Request

GET /auth/token/refresh

Cookie: refresh_token=<current_refresh_token>

Response

204 No Content

#Delete user

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)

nhost-js-sdk

not implemented

Request

POST /auth/delete

Set-Cookie: refresh_token=...
Set-Cookie: permission_variables=...

Response

204 No Content

#Change password

For users to change their password when they are logged in and remember their previous password.

nhost-js-sdk

auth.changePassword(oldPassword: string, newPassword: string);

Request

POST /auth/change-password

Set-Cookie: refresh_token=...
Set-Cookie: permission_variables=...
{
  "old_password": "<old password>",
  "new_password": "<new password>"
}

Response

204 No Content

#Request to change password

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.

nhost-js-sdk

auth.requestPasswordChange(email: string);

Request

POST /auth/change-password/request

{
  "email": "<user's email>"
}

Response

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

Change password with ticket from the email.

nhost-js-sdk

auth.confirmPasswordChange(newPassword: string, ticket: string);

Request

POST /auth/change-password/change

{
  "new_password": "<new password>",
  "ticket": "<ticket>"
}

Response

204 No Content

#Generate MFA QR-code

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.

nhost-js-sdk

auth.MFAGenerate(code: string, ticket: string);

Request

POST /auth/mfa/generate

Response

{
  "image_url": "<base64 data image of the qe code>",
  "otp_secret": "<otp secret>"
}


#Enable MFA

Enable MFA (Multi-Factor Authentication). Use the code (one-time password) in the user's password manager

nhost-js-sdk

auth.MFAEnable(code: string);

Request

POST /auth/mfa/enable

{
  "code": "123456"
}

Response

204 No Content

#Disable MFA

Disable MFA (Multi-Factor Authentication). Use the code (one-time password) in the user's password manager

nhost-js-sdk

Not implemented yet

Request

POST /auth/mfa/disable

{
  "code": "code from mfa client"
}

Response

204 No Content

#TOTP login

Time-based One-Time Password login. Use the ticket from Login response body and the code from the user's password manager.

nhost-js-sdk

auth.MFATotp(code: string, ticket: string);

Request

POST /auth/mfa/generate

Response

{
  "image_url": "<base64 data image of the qe code>",
  "otp_secret": "<otp secret>"
}