Users

Users are stored in the auth.users table in the database.

Creating Users

Users should be created using the sign-up or sign-in flows as described under sign-in methods.

• Never create users directly via GraphQL or database, unless you import users from an external system.
• Never modify the database schema for the auth.users table.
• Never modify the GraphQL root queries or fields for any of the tables in the auth schema.

You're allowed to:

• Add and remove your GraphQL relationships for the users table and other tables in the auth schema.
• Create, edit and delete permissions for the users table and other tables in the auth schema.

Roles

Each user has one default role and an array of allowed roles. These roles are used to resolve permissions for requests to GraphQL and Storage.

When the user makes a request, only one role is used to resolve permissions. The default role is used if no role is explicitly specified. Users can only make requests using the default role or one of the allowed roles.

You can manage users' default roles and allowed roles in the Dashboard at Auth.

Default Role

The default role is used when no role is specified in the request. By default, users' default role is user.

You can change what the default role for new users should be at Settings -> Roles and Permissions.

Allowed Roles

Allowed roles are roles the user is allowed to use when making a request. Usually, you would change the role from user (the default role) to some other role because you want to use a different role to resolve permissions for a particular request.

By default, users have two allowed roles:

• user (also the default role)
• me

You can change what the default role for new users should be at Settings -> Roles and Permissions.

Assign Allowed Roles

It's possible to give users a subset of allowed roles during signup.

Example: Only give the user role (without the me role) for the user's allowed roles:

await nhost.auth.signUp({
  email: 'joe@example.com',
  password: 'secret-password'
  options: {
    allowedRoles: ['user']
  }
})

Set Role for GraphQL Requests

When no request role is specified, the user's default role will be used:

await nhost.graphql.request(QUERY, {})

If you want to make a GraphQL request using a specific role, you can do so by using the x-hasura-role header, like this:

await nhost.graphql.request(
  QUERY,
  {},
  {
    headers: {
      'x-hasura-role': 'me'
    }
  }
)

If the request is not part of the user's allowed roles, the request will fail.

Metadata

You can store custom information about the user in the metadata column of the users table. The metadata column is of type JSONB so any JSON data can be stored.

Example: Add metadata to a user during sign-up:

await nhost.auth.signUp({
  email: 'joe@example.com',
  password: 'secret-password',
  options: {
    metadata: {
      birthYear: 1989,
      town: 'Stockholm',
      likes: ['Postgres', 'GraphQL', 'Hasura', 'Authentication', 'Storage', 'Serverless Functions']
    }
  }
})

Get User Information using GraphQL

Example: Get all users.

query {
  users {
    id
    displayName
    email
    metadata
  }
}

Example: Get a single user.

query {
  user(id: "<user-id>") {
    id
    displayName
    email
    metadata
  }
}

Import Users

If you have users in a different system, you can import them into Nhost. When importing users you should insert the users directly into the database instead of using the authentication endpoints (/signup/email-password) to avoid sending unnecessary transactional emails.

It's possible to insert users via GraphQL or SQL.

GraphQL

Make a GraphQL request to insert a user like this:

mutation insertUser($user: users_insert_input!) {
  insertUser(object: $user) {
    id
  }
}

SQL

Connect directly to the database and insert a user like this:

INSERT INTO auth.users (id, email, display_name, password_hash, ..) VALUES ('<user-id>', '<email>', '<display-name>', '<password-hash>', ..);

Passwords are hashed using bcrypt.