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 theauth
schema. - Create, edit and delete permissions for the
users
table and other tables in theauth
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.