v15

latestOpenAPI 3.0.0MIT Licenseraw.githubusercontent.com2026-08-016088119.5 KB

authentication

Sign up with email and password

Register a new user account with email and password. Returns a session if email verification is not required, otherwise returns null session.

post/signup/email-password

Request body

emailstring email required

Email address for the new user account

passwordstring required

Password for the new user account

codeChallengestring

PKCE code challenge (S256). When provided and email verification is required, the verification redirect will contain an authorization code instead of a refresh token.

Example request

{
  "email": "john.smith@nhost.io",
  "password": "Str0ngPassw#ord-94|%",
  "options": {
    "allowedRoles": [
      "me",
      "user"
    ],
    "defaultRole": "user",
    "displayName": "John Smith",
    "locale": "en",
    "metadata": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "redirectTo": "https://my-app.com/catch-redirection"
  }
}

Response

Registration successful. If email verification is required, session will be null.

Example response

{
  "session": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "accessTokenExpiresIn": 900,
    "refreshTokenId": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24",
    "refreshToken": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24",
    "user": {
      "avatarUrl": "https://myapp.com/avatars/user123.jpg",
      "createdAt": "2023-01-15T12:34:56Z",
      "defaultRole": "user",
      "displayName": "John Smith",
      "email": "john.smith@nhost.io",
      "emailVerified": true,
      "id": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24",
      "locale": "en",
      "metadata": {
        "firstName": "John",
        "lastName": "Smith"
      },
      "phoneNumber": "+12025550123",
      "roles": [
        "user",
        "customer"
      ]
    }
  }
}