Roles

Each user can have one or more roles. By default, each user has the roles user and me.

A role is used to set Hasura Permissions and Storage Security Rules.

A user's roles are defined in the JWT-token that is automatically generated when a user logs in.

Here's an example:

{
  "https://hasura.io/jwt/claims": {
    "x-hasura-allowed-roles": ["user", "me"],
    "x-hasura-default-role": "user",
    "x-hasura-user-id": "c8ee8353-b886-4530-9089-631ea7fd4c8a"
  },
  "iat": 1595146465,
  "exp": 1595147365
}

The x-hasura-default-role claim is the default role of the user. This role is used for every request unless you change the role manually during the request (See Change role in a GraphQL request). By default the default role is user.

A user can have multiple allowed roles. Allowed roles are roles that the user can use to make a GraphQL request. A GraphQL request can only use one role per request.

The me role can be used to set user specific permission for the own user. For example, you might want to allow all users (user role) to select id and display_name for all users in your app. But each user should also be able to see their own birthday. You can use the me role to select the birthday.

A user can override the default role in a GraphQL API request by setting the x-hasura-role header. The new role must be in the x-hasura-allowed-roles array.

As an example, let's say a user has the roles user, me and editor:

x-hasura-default-role: user
x-hasura-allowed-roles: ["user", "me", "editor"]

Then the user can make a request as an editor like this:

const { loading, error, data } = useQuery(MY_QUERY, {
  context: {
    headers: {
      "x-hasura-role": "editor",
    },
  },
});

A user can have multiple default roles directly on registration. The default allowed user roles can be set in Settings -> Authentication -> DEFAULT ALLOWED ROLES.

If a user is not logged-in and no header or token is sent with the GraphQL request, Hasura resolves the request using the public role.

HASURA_GRAPHQL_UNAUTHORIZED_ROLE is set to public by default for all Nhost projects.