API Reference for Nhost Authentication

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

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