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.