Skip to main content

Tokens

Nhost Authentication makes use of two types of tokens:

  • Access token - used to authenticate a user and access APIs.
  • Refresh token - used to get a new access token.

Users get both an access token and a refresh token when they sign in.

info

If you're using the Nhost JavaScript client, all tokens are automatically set and updated for you. But it can still be good to understand how they work.

Access Token​

An access token (also called JSON Web Token or JWT) contains information about the user such as the user id. Users send this token to the Nhost services (GraphQL, Auth, Storage, Serverless Functions) to let the services know who's making the request so the services can verify the user's identity and resolve the correct permissions.

The access token is added as an Authorization header when making a request, like this:

Header
Authorization: Bearer <access_token>

Here's an example of an encoded access token:

eyJhbGciOiJIUzI1NiJ9.eyJodHRwczovL2hhc3VyYS5pby9qd3QvY2xhaW1zIjp7IngtaGFzdXJhLWFsbG93ZWQtcm9sZXMiOlsibWUiLCJ1c2VyIl0sIngtaGFzdXJhLWRlZmF1bHQtcm9sZSI6InVzZXIiLCJ4LWhhc3VyYS11c2VyLWlkIjoiMTUzODYzZjktZTQwMC00Njg2LTgyMTEtMzI0OGNjYWY2MGJhIiwieC1oYXN1cmEtdXNlci1pcy1hbm9ueW1vdXMiOiJmYWxzZSJ9LCJzdWIiOiIxNTM4NjNmOS1lNDAwLTQ2ODYtODIxMS0zMjQ4Y2NhZjYwYmEiLCJpc3MiOiJoYXN1cmEtYXV0aCIsImlhdCI6MTY1Mzg5MjA5NCwiZXhwIjoxNjUzODkyOTk0fQ.9nVL2Lj8KWBW3WrjJr4tPNH3_29qJKKKSDRNYebhiHI

The decoded payload of this access token is a JSON object that looks like this:

{
  "https://hasura.io/jwt/claims": {
    "x-hasura-allowed-roles": ["me", "user"],
    "x-hasura-default-role": "user",
    "x-hasura-user-id": "153863f9-e400-4686-8211-3248ccaf60ba",
    "x-hasura-user-is-anonymous": "false"
  },
  "sub": "153863f9-e400-4686-8211-3248ccaf60ba",
  "iss": "hasura-auth",
  "iat": 1653892094,
  "exp": 1653892994
}

The token contains information about the user id, default role, allowed roles, if the user is anonymous or not, and other metadata.

The claims under https://hasura.io/jwt/claims are the same claims that are used by the GraphQL API to create permissions. The claims (x-hasura-*) are also called permission variables. It's possible to add more permission variables to the access token.

info

You can manually decode an access token using JWT.io.

The token is cryptographically signed by Nhost Auth, which means that all other Nhost services can trust the information in the token.

info

Use the NHOST_JWT_SECRET system environment variable to verify access tokens in Serverless Functions. Here's a guide on how to Get the authenticated user in a Serverless Function.

The access token can not be revoked. Instead, the token is only valid for 15 minutes. The user can get a new access token by using the refresh token.

Refresh Token​

A refresh token is used to request a new access token. Refresh tokens are long-lived tokens stored in the database in the auth.refresh_tokens table.

Refresh tokens are valid for 30 days.

To revoke a refresh token, simply delete it from the database.