Sign in with email and password

POST

/signin/email-password

• Nhost Authentication API Server

Authenticate a user with their email and password. Returns a session object or MFA challenge if two-factor authentication is enabled.

Request Body ^required

User credentials for email and password authentication

Request to authenticate using email and password

object

email

required

User’s email address

string format: email

Example

john.smith@nhost.io

password

required

User’s password

string

>= 3 characters <= 50 characters

Example

Str0ngPassw#ord-94|%

Responses

200

Authentication successful. If MFA is enabled, a challenge will be returned instead of a session.

Response for email-password authentication that may include a session or MFA challenge

object

session

User authentication session containing tokens and user information

object

accessToken

required

JWT token for authenticating API requests

string

Example

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

accessTokenExpiresIn

required

Expiration time of the access token in seconds

integer format: int64

Example

900

refreshTokenId

required

Identifier for the refresh token

string

/\b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b/

Example

2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24

refreshToken

required

Token used to refresh the access token

string

/\b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b/

Example

2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24

user

User profile and account information

object

avatarUrl

required

URL to the user’s profile picture

string

Example

https://myapp.com/avatars/user123.jpg

createdAt

required

Timestamp when the user account was created

string format: date-time

Example

2023-01-15T12:34:56Z

defaultRole

required

Default authorization role for the user

string

Example

user

displayName

required

User’s display name

string

Example

John Smith

email

User’s email address

string format: email

Example

john.smith@nhost.io

emailVerified

required

Whether the user’s email has been verified

boolean

Example

true

id

required

Unique identifier for the user

string

/\b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b/

Example

2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24

isAnonymous

required

Whether this is an anonymous user account

boolean

locale

required

User’s preferred locale (language code)

string

>= 2 characters <= 3 characters

Example

en

metadata

required

Custom metadata associated with the user

object

key

additional properties

any

Example

{
  "firstName": "John",
  "lastName": "Smith"
}

phoneNumber

User’s phone number

string

Example

+12025550123

phoneNumberVerified

required

Whether the user’s phone number has been verified

boolean

roles

required

List of roles assigned to the user

Array<string>

Example

[
  "user",
  "customer"
]

activeMfaType

Active MFA type for the user

string

nullable

mfa

Challenge payload for multi-factor authentication

object

ticket

required

Ticket to use when completing the MFA challenge

string

Example

mfaTotp:abc123def456

default

An error occurred while processing the request

Standardized error response

object

status

required

HTTP status error code

integer

Example

400

message

required

Human-friendly error message

string

Example

Invalid email format

error

required

Error code identifying the specific application error

string

Allowed values: default-role-must-be-in-allowed-roles disabled-endpoint disabled-user email-already-in-use email-already-verified forbidden-anonymous internal-server-error invalid-email-password invalid-request locale-not-allowed password-too-short password-in-hibp-database redirectTo-not-allowed role-not-allowed signup-disabled unverified-user user-not-anonymous invalid-pat invalid-refresh-token invalid-ticket disabled-mfa-totp no-totp-secret invalid-totp mfa-type-not-found totp-already-active invalid-state oauth-token-echange-failed oauth-profile-fetch-failed oauth-provider-error invalid-otp cannot-send-sms provider-account-already-linked